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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: validibot-shared
-Version: 0.10.0
+Version: 0.12.0
 Summary: Shared library for data interchange between Validibot and validator containers
 Project-URL: Homepage, https://validibot.com
 Project-URL: Documentation, https://docs.validibot.com
@@ -24,10 +24,11 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Scientific/Engineering
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.10
+Requires-Dist: defusedxml<0.8,>=0.7.1
 Requires-Dist: pydantic<3.0,>=2.13
 Provides-Extra: dev
 Requires-Dist: pytest==9.1.1; extra == 'dev'
-Requires-Dist: ruff==0.15.18; extra == 'dev'
+Requires-Dist: ruff==0.15.20; extra == 'dev'
 Description-Content-Type: text/markdown
 
 <div align="center">

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

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

validibot_shared-0.12.0/tests/test_schematron_envelopes.py

@@ -0,0 +1,204 @@
+"""Tests for the Schematron container contract (ADR-2026-07-01, D4b/D9).
+
+The Schematron validator ships the author's rules **inline as text** (the
+SHACL ``shapes_text`` pattern — the container compiles them itself), and its
+outputs carry an ``engine_status`` failure taxonomy where ``passed`` is
+*tri-state* — True/False when the engine ran, ``None`` (unknown) when it
+could not. These tests pin those contract properties so a refactor cannot
+silently weaken them: the Django side and the validator backend both program
+against exactly this shape.
+"""
+
+import pytest
+from pydantic import ValidationError
+
+from validibot_shared.schematron.envelopes import (
+    ENGINE_ERROR_RULES_INVALID,
+    ENGINE_STATUS_OK,
+    ENGINE_STATUS_TIMEOUT,
+    SchematronFinding,
+    SchematronInputEnvelope,
+    SchematronInputs,
+    SchematronOutputEnvelope,
+    SchematronOutputs,
+    build_schematron_input_envelope,
+)
+from validibot_shared.validations.envelopes import (
+    SupportedMimeType,
+    ValidationStatus,
+    ValidatorType,
+)
+
+# Test constants to avoid magic values
+DEFAULT_MAX_FINDINGS = 500
+DEFAULT_XSLT_TIMEOUT = 60
+TEST_ERROR_COUNT = 3
+RULES_SHA = "b" * 64
+
+SCH_SOURCE = (
+    '<schema xmlns="http://purl.oclc.org/dsdl/schematron">'
+    "<pattern><rule context='/'><assert test='true()'>ok</assert></rule>"
+    "</pattern></schema>"
+)
+
+
+class _ValidatorStub:
+    """Duck-typed validator (id/validation_type/version) for the builder."""
+
+    id = "val-1"
+    validation_type = "SCHEMATRON"
+    version = "1"
+
+
+def _inputs(**overrides) -> SchematronInputs:
+    base = {
+        "schematron_text": SCH_SOURCE,
+        "schematron_sha256": RULES_SHA,
+    }
+    base.update(overrides)
+    return SchematronInputs(**base)
+
+
+def test_inputs_carry_inline_rules_and_limit_defaults():
+    """Inputs ship the rules inline with provenance sha and D8 defaults.
+
+    Inline text is the whole delivery model (no staging, no artefact URIs):
+    the container gets everything it needs from the envelope alone, exactly
+    like SHACL's shapes_text.
+    """
+    inputs = _inputs()
+
+    assert inputs.schematron_text == SCH_SOURCE
+    assert inputs.schematron_sha256 == RULES_SHA
+    assert inputs.max_findings == DEFAULT_MAX_FINDINGS
+    assert inputs.xslt_timeout_seconds == DEFAULT_XSLT_TIMEOUT
+
+
+def test_inputs_require_the_rules_text():
+    """Omitting schematron_text is a validation error, not a default.
+
+    An input envelope without rules would force the container to run
+    nothing and report... something. Refuse at the contract layer.
+    """
+    with pytest.raises(ValidationError):
+        SchematronInputs()
+
+
+def test_outputs_default_to_unknown_passed_not_false():
+    """``passed`` defaults to None — unknown, not failed (D9).
+
+    A default of False would make an unpopulated envelope read as "the
+    document failed the rules"; None forces every consumer to distinguish
+    "engine didn't run" from "rules failed".
+    """
+    outputs = SchematronOutputs()
+    assert outputs.passed is None
+    assert outputs.engine_status == ENGINE_STATUS_OK
+
+
+def test_engine_failure_shapes_round_trip():
+    """Timeout and rules-invalid outputs serialize and re-validate losslessly.
+
+    The callback path deserializes output.json with this model; the D9
+    fields must survive the JSON round trip exactly, including the
+    machine hint that lets Django distinguish "your rules don't compile"
+    from a generic engine error.
+    """
+    timeout = SchematronOutputs(
+        engine_status=ENGINE_STATUS_TIMEOUT,
+        engine_message="Transform exceeded 60s",
+        passed=None,
+    )
+    invalid_rules = SchematronOutputs(
+        engine_status="error",
+        engine_error_code=ENGINE_ERROR_RULES_INVALID,
+        engine_message="Schematron failed to compile: unexpected element",
+        passed=None,
+    )
+    for outputs, status in (
+        (timeout, ValidationStatus.FAILED_RUNTIME),
+        (invalid_rules, ValidationStatus.FAILED_RUNTIME),
+    ):
+        envelope = SchematronOutputEnvelope(
+            run_id="run-1",
+            validator={"id": "v1", "type": ValidatorType.SCHEMATRON, "version": "1"},
+            status=status,
+            timing={},
+            outputs=outputs,
+        )
+        restored = SchematronOutputEnvelope.model_validate(
+            envelope.model_dump(mode="json"),
+        )
+        assert restored.outputs.engine_status == outputs.engine_status
+        assert restored.outputs.engine_error_code == outputs.engine_error_code
+        assert restored.outputs.passed is None
+
+
+def test_findings_map_and_provenance_round_trip():
+    """Findings keep native ids/locations; provenance keeps the rules sha."""
+    outputs = SchematronOutputs(
+        engine_status=ENGINE_STATUS_OK,
+        passed=False,
+        error_count=TEST_ERROR_COUNT,
+        finding_rule_ids_by_severity={"BR-CO-15": "ERROR", "BR-05": "WARNING"},
+        findings=[
+            SchematronFinding(
+                rule_id="BR-CO-15",
+                message="Totals must reconcile.",
+                severity="ERROR",
+                location_xpath="/Invoice/LegalMonetaryTotal",
+                flag="fatal",
+            ),
+        ],
+        schematron_sha256=RULES_SHA,
+        query_binding="xslt2",
+        engine="SaxonC-HE 12.9",
+    )
+
+    restored = SchematronOutputs.model_validate(outputs.model_dump(mode="json"))
+    assert restored.finding_rule_ids_by_severity["BR-CO-15"] == "ERROR"
+    assert restored.findings[0].rule_id == "BR-CO-15"
+    assert restored.findings[0].location_xpath == "/Invoice/LegalMonetaryTotal"
+    assert restored.schematron_sha256 == RULES_SHA
+    assert restored.query_binding == "xslt2"
+
+
+def test_outputs_forbid_unknown_fields():
+    """extra="forbid" holds — a typo'd field fails loudly, not silently.
+
+    Contract models must reject unknown keys so a mismatched backend/Django
+    version pair surfaces as an explicit error instead of dropped data.
+    This also guards the 0.11 → 0.12 break: old pack_* fields are refused.
+    """
+    with pytest.raises(ValidationError):
+        SchematronOutputs(engine_status="ok", pack_id="stale-field")
+
+
+def test_build_schematron_input_envelope_assembles_the_xml_submission():
+    """The builder produces a valid envelope with an XML primary input.
+
+    Pins the file-item conventions (name/mime/role) the container reads and
+    that ``ValidatorType.SCHEMATRON`` exists — the builder would crash
+    without the enum member.
+    """
+    envelope = build_schematron_input_envelope(
+        run_id="run-1",
+        validator=_ValidatorStub(),
+        org_id="org-1",
+        org_name="ValidiBot",
+        workflow_id="wf-1",
+        step_id="step-1",
+        step_name="Peppol rules",
+        submission_uri="gs://bucket/run-1/submission.xml",
+        inputs=_inputs(),
+        callback_url="https://example.com/callback",
+        execution_bundle_uri="gs://bucket/run-1/",
+    )
+
+    assert isinstance(envelope, SchematronInputEnvelope)
+    assert envelope.validator.type == ValidatorType.SCHEMATRON
+    file_item = envelope.input_files[0]
+    assert file_item.name == "submission.xml"
+    assert file_item.mime_type == SupportedMimeType.APPLICATION_XML
+    assert file_item.role == "primary-model"
+    assert envelope.inputs.schematron_text == SCH_SOURCE

validibot_shared-0.12.0/tests/test_schematron_svrl.py

@@ -0,0 +1,288 @@
+"""Unit tests for the canonical SVRL parser (ADR-2026-07-01, D3/D10).
+
+``validibot_shared.schematron.svrl`` is the pure SVRL → findings/summary
+parser both consumers rely on — the validator backend container (parsing
+Saxon's SVRL into ``SchematronOutputs``) and the Django app (fixture and
+round-trip tests). These tests feed it canned SVRL documents and pin the
+D3/D10 contract:
+
+- ``svrl:failed-assert`` AND ``svrl:successful-report`` are active findings
+  handled identically — element type never drives severity.
+- Severity resolves ``@flag`` → ``@role`` → fail-closed ERROR, so nothing
+  publisher-authored is silently downgraded.
+- ``svrl:fired-rule`` counts rules/contexts evaluated, never assertions.
+- The ``finding_rule_ids_by_severity`` map is the pinned CEL contract
+  ({rule_id: severity}, most severe wins).
+- Truncation keeps ERROR findings first and is always explicit, while the
+  aggregate counts still reflect the FULL totals.
+
+Different Schematron compilers emit slightly different SVRL dialects, so the
+parser must be defensive — the un-namespaced-SVRL test guards that.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from validibot_shared.schematron.svrl import (
+    SEVERITY_ERROR,
+    SEVERITY_INFO,
+    SEVERITY_WARNING,
+    SvrlParseError,
+    parse_svrl,
+)
+
+# Named test values (avoid magic literals in assertions).
+TRUNCATION_CAP = 2
+TOTAL_FINDINGS_FOR_TRUNCATION = 5
+EXPECTED_SUPPRESSED = TOTAL_FINDINGS_FOR_TRUNCATION - TRUNCATION_CAP
+EXPECTED_FIRED_RULES = 2
+ERRORS_IN_TRUNCATION_BODY = 2
+WARNINGS_IN_TRUNCATION_BODY = 2
+
+
+def _svrl(body: str) -> str:
+    """Wrap finding elements in a minimal schematron-output document."""
+    return (
+        '<svrl:schematron-output xmlns:svrl="http://purl.oclc.org/dsdl/svrl">'
+        f"{body}"
+        "</svrl:schematron-output>"
+    )
+
+
+def _failed_assert(
+    *,
+    rule_id: str = "VB-X",
+    flag: str = "",
+    role: str = "",
+    location: str = "/Invoice",
+    text: str = "Something failed.",
+) -> str:
+    attrs = f' id="{rule_id}" location="{location}"'
+    if flag:
+        attrs += f' flag="{flag}"'
+    if role:
+        attrs += f' role="{role}"'
+    return (
+        f"<svrl:failed-assert{attrs}><svrl:text>{text}</svrl:text></svrl:failed-assert>"
+    )
+
+
+# ── Severity resolution: @flag → @role → fail-closed ERROR ──────────────────
+
+
+def test_failed_assert_flag_fatal_maps_to_error():
+    """flag="fatal" resolves to ERROR and id/location survive the mapping.
+
+    The rule id and location are the whole value proposition (D10): they make
+    findings actionable and cross-referenceable against the published rules.
+    """
+    summary = parse_svrl(
+        _svrl(
+            _failed_assert(
+                rule_id="VB-CO-15",
+                flag="fatal",
+                location="/Invoice/LegalMonetaryTotal",
+            ),
+        ),
+    )
+
+    assert summary.error_count == 1
+    assert not summary.passed
+    finding = summary.findings[0]
+    assert finding.rule_id == "VB-CO-15"
+    assert finding.severity == SEVERITY_ERROR
+    assert finding.location == "/Invoice/LegalMonetaryTotal"
+    assert finding.flag == "fatal"
+
+
+def test_successful_report_is_an_active_finding_handled_identically():
+    """A svrl:successful-report with flag="fatal" is an ERROR finding.
+
+    This is the D3 rule the naive implementation gets wrong: a ``<report>``
+    can carry a publisher-authored *error*, so the element type must never
+    drive severity — only @flag/@role do.
+    """
+    summary = parse_svrl(
+        _svrl(
+            '<svrl:successful-report id="VB-R-01" flag="fatal" location="/a">'
+            "<svrl:text>Reported error.</svrl:text>"
+            "</svrl:successful-report>",
+        ),
+    )
+
+    assert summary.error_count == 1
+    assert summary.findings[0].severity == SEVERITY_ERROR
+    assert summary.findings[0].element == "successful-report"
+
+
+def test_role_is_the_fallback_when_flag_is_absent():
+    """@role maps warning→WARNING and information→INFO when @flag is missing.
+
+    The official packs use both spellings families (warn/warning,
+    info/information); the resolver accepts them all.
+    """
+    summary = parse_svrl(
+        _svrl(
+            _failed_assert(rule_id="VB-W", role="warning")
+            + _failed_assert(rule_id="VB-I", role="information"),
+        ),
+    )
+
+    by_id = {f.rule_id: f for f in summary.findings}
+    assert by_id["VB-W"].severity == SEVERITY_WARNING
+    assert by_id["VB-I"].severity == SEVERITY_INFO
+    assert summary.warning_count == 1
+    assert summary.info_count == 1
+    # Warnings/info alone never fail a Schematron step (D3).
+    assert summary.passed
+
+
+def test_flag_wins_over_role():
+    """When both attributes exist, @flag is authoritative (D3 resolution order)."""
+    summary = parse_svrl(
+        _svrl(_failed_assert(rule_id="VB-B", flag="fatal", role="warning")),
+    )
+    assert summary.findings[0].severity == SEVERITY_ERROR
+
+
+def test_fail_closed_to_error_when_neither_flag_nor_role_present():
+    """A finding with no severity attributes fail-closes to ERROR.
+
+    Fail-open (defaulting to INFO) would silently downgrade publisher-authored
+    rules whose pack relies on a default phase severity — the exact bug class
+    D3 forbids.
+    """
+    summary = parse_svrl(_svrl(_failed_assert(rule_id="VB-N")))
+    assert summary.findings[0].severity == SEVERITY_ERROR
+    assert summary.error_count == 1
+
+
+# ── Message text extraction ──────────────────────────────────────────────────
+
+
+def test_message_text_collapses_whitespace_and_inline_markup():
+    """svrl:text content survives inline markup and layout whitespace.
+
+    Publisher messages contain inline elements (emph/span) and authored
+    newlines; the human-readable message must come out flat and readable.
+    """
+    summary = parse_svrl(
+        _svrl(
+            '<svrl:failed-assert id="VB-T" flag="fatal" location="/a">'
+            "<svrl:text>Total \n   must <emph>equal</emph>\n sum.</svrl:text>"
+            "</svrl:failed-assert>",
+        ),
+    )
+    assert summary.findings[0].message == "Total must equal sum."
+
+
+# ── fired-rule counting ──────────────────────────────────────────────────────
+
+
+def test_fired_rule_count_counts_rules_not_assertions():
+    """svrl:fired-rule elements count evaluated rules/contexts — nothing else.
+
+    The review explicitly renamed this signal away from "assertion count":
+    a fired rule is a context the engine evaluated, not an assertion that
+    failed. Two fired rules + one failed assert must yield 2 / 1.
+    """
+    summary = parse_svrl(
+        _svrl(
+            '<svrl:fired-rule context="/Invoice"/>'
+            '<svrl:fired-rule context="/Invoice/Total"/>'
+            + _failed_assert(rule_id="VB-1", flag="fatal"),
+        ),
+    )
+    assert summary.fired_rule_count == EXPECTED_FIRED_RULES
+    assert summary.error_count == 1
+
+
+# ── The finding_rule_ids_by_severity map (CEL contract) ─────────────────────
+
+
+def test_rule_id_map_shape_and_most_severe_wins():
+    """The map is {rule_id: severity} and the most severe occurrence wins.
+
+    This is the pinned D2 CEL contract: key membership tests
+    (``"VB-D" in o.finding_rule_ids_by_severity``) and severity-aware gates
+    both depend on this exact shape. A rule firing at WARNING in one context
+    and ERROR in another must surface as ERROR.
+    """
+    summary = parse_svrl(
+        _svrl(
+            _failed_assert(rule_id="VB-D", role="warning")
+            + _failed_assert(rule_id="VB-D", flag="fatal")
+            + _failed_assert(rule_id="VB-W", role="warning"),
+        ),
+    )
+    assert summary.finding_rule_ids_by_severity == {
+        "VB-D": SEVERITY_ERROR,
+        "VB-W": SEVERITY_WARNING,
+    }
+
+
+# ── Truncation (D10: capped, never silent) ───────────────────────────────────
+
+
+def test_truncation_keeps_errors_first_and_counts_stay_full():
+    """Capping keeps ERROR findings first and records the suppressed count.
+
+    Two invariants: (1) the kept findings are ordered ERROR → WARNING → INFO
+    so the most actionable rows survive; (2) the aggregate counts reflect the
+    FULL document, so "clean-ish" and "thousands of errors, capped" can never
+    look the same to a CEL gate.
+    """
+    body = (
+        _failed_assert(rule_id="VB-I1", role="info")
+        + _failed_assert(rule_id="VB-W1", role="warning")
+        + _failed_assert(rule_id="VB-E1", flag="fatal")
+        + _failed_assert(rule_id="VB-E2", flag="error")
+        + _failed_assert(rule_id="VB-W2", role="warning")
+    )
+    summary = parse_svrl(_svrl(body), max_findings=TRUNCATION_CAP)
+
+    assert summary.findings_truncated
+    assert summary.findings_suppressed_count == EXPECTED_SUPPRESSED
+    assert len(summary.findings) == TRUNCATION_CAP
+    # ERROR findings survive the cap ahead of warnings/info.
+    assert {f.rule_id for f in summary.findings} == {"VB-E1", "VB-E2"}
+    # Aggregates are computed pre-cap.
+    assert summary.error_count == ERRORS_IN_TRUNCATION_BODY
+    assert summary.warning_count == WARNINGS_IN_TRUNCATION_BODY
+    assert summary.info_count == 1
+    assert len(summary.finding_rule_ids_by_severity) == TOTAL_FINDINGS_FOR_TRUNCATION
+
+
+# ── Dialect tolerance + input guards ─────────────────────────────────────────
+
+
+def test_unnamespaced_svrl_is_tolerated():
+    """SVRL without the namespace still parses (compiler-dialect defensiveness).
+
+    Some Schematron toolchains emit un-namespaced SVRL; the parser matches on
+    local names so those reports still map to findings.
+    """
+    summary = parse_svrl(
+        "<schematron-output>"
+        '<fired-rule context="/a"/>'
+        '<failed-assert id="VB-U" flag="fatal" location="/a">'
+        "<text>Unnamespaced.</text>"
+        "</failed-assert>"
+        "</schematron-output>",
+    )
+    assert summary.fired_rule_count == 1
+    assert summary.findings[0].rule_id == "VB-U"
+
+
+def test_empty_and_malformed_svrl_raise():
+    """Empty or non-XML input raises SvrlParseError rather than passing.
+
+    Silently returning an empty summary for garbage input would read as
+    "zero findings" — i.e. a pass — which is exactly the fail-open behaviour
+    the D9 taxonomy exists to prevent.
+    """
+    with pytest.raises(SvrlParseError):
+        parse_svrl("")
+    with pytest.raises(SvrlParseError):
+        parse_svrl("this is not XML <")

validibot_shared-0.12.0/validibot_shared/schematron/__init__.py

@@ -0,0 +1,49 @@
+"""Schematron Advanced validator envelopes and models."""
+
+from validibot_shared.schematron.envelopes import (
+    ENGINE_ERROR_BACKEND_UNAVAILABLE,
+    ENGINE_ERROR_RULES_INVALID,
+    ENGINE_STATUS_ERROR,
+    ENGINE_STATUS_OK,
+    ENGINE_STATUS_TIMEOUT,
+    QUERY_BINDING_XSLT1,
+    QUERY_BINDING_XSLT2,
+    SchematronFinding,
+    SchematronInputEnvelope,
+    SchematronInputs,
+    SchematronOutputEnvelope,
+    SchematronOutputs,
+    build_schematron_input_envelope,
+)
+from validibot_shared.schematron.svrl import (
+    SEVERITY_ERROR,
+    SEVERITY_INFO,
+    SEVERITY_WARNING,
+    SvrlFinding,
+    SvrlParseError,
+    SvrlSummary,
+    parse_svrl,
+)
+
+__all__ = [
+    "ENGINE_ERROR_BACKEND_UNAVAILABLE",
+    "ENGINE_ERROR_RULES_INVALID",
+    "ENGINE_STATUS_ERROR",
+    "ENGINE_STATUS_OK",
+    "ENGINE_STATUS_TIMEOUT",
+    "QUERY_BINDING_XSLT1",
+    "QUERY_BINDING_XSLT2",
+    "SEVERITY_ERROR",
+    "SEVERITY_INFO",
+    "SEVERITY_WARNING",
+    "SchematronFinding",
+    "SchematronInputEnvelope",
+    "SchematronInputs",
+    "SchematronOutputEnvelope",
+    "SchematronOutputs",
+    "SvrlFinding",
+    "SvrlParseError",
+    "SvrlSummary",
+    "build_schematron_input_envelope",
+    "parse_svrl",
+]

validibot_shared-0.12.0/validibot_shared/schematron/envelopes.py

@@ -0,0 +1,296 @@
+"""
+Pydantic envelopes for the Schematron Advanced validator backend.
+
+The Schematron validator is an Advanced validator — it runs in an isolated
+container/Cloud Run Job rather than inside the Django worker. Schematron
+rules compile to XSLT (a full programming language), so author-uploaded
+rules are executable code and only ever run inside the sandboxed container:
+no database, no secrets, no network egress, locked-down engine
+(ADR-2026-07-01, decisions D4/D8).
+
+These schemas define the contract between Django and the Schematron
+container:
+
+- **Input envelope**: the XML submission (as an ``InputFileItem`` URI) plus
+  the author's Schematron rules **inline as text** — exactly how SHACL
+  ships its merged shapes text. Django resolves the rules from the step's
+  ``Ruleset`` before dispatch; the container compiles them (SchXslt2 →
+  XSLT, baked into the image as fixed tooling) and runs the result over the
+  submission. The D8 resource limits ride along, already clamped
+  Django-side; the container re-clamps defensively.
+- **Output envelope**: the parsed SVRL summary — per-severity counts, the
+  ``finding_rule_ids_by_severity`` map, structured findings preserving
+  native rule ids/locations — plus ``engine_status`` (D9: findings are only
+  meaningful when the engine actually ran) and provenance (the sha256 of
+  the executed rules, the detected query binding, and the engine that ran).
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+from validibot_shared.validations.envelopes import (
+    ExecutionContext,
+    InputFileItem,
+    SupportedMimeType,
+    ValidationInputEnvelope,
+    ValidationOutputEnvelope,
+    ValidatorInfo,
+    ValidatorType,
+)
+
+# ── D9 engine status: "couldn't run the rules" ≠ "the rules failed" ────────
+# ``passed``/findings on the outputs are only meaningful when the engine
+# status is OK. On error/timeout, Django surfaces a single reserved
+# infrastructure finding and never synthesises rule findings.
+ENGINE_STATUS_OK = "ok"
+ENGINE_STATUS_ERROR = "error"
+ENGINE_STATUS_TIMEOUT = "timeout"
+
+# Machine hints for ``SchematronOutputs.engine_error_code`` — Django maps
+# these to its reserved ``schematron.*`` finding codes.
+#
+# ``rules_invalid``: the author's uploaded Schematron failed to compile.
+# That's a workflow-authoring problem, not a fact about the submitted
+# document — the submitter's run still reads "the check couldn't run".
+ENGINE_ERROR_RULES_INVALID = "rules_invalid"
+ENGINE_ERROR_BACKEND_UNAVAILABLE = "backend_unavailable"
+
+# Schematron query bindings (declared by the .sch root's ``queryBinding``
+# attribute; the container detects and echoes it for provenance).
+QUERY_BINDING_XSLT1 = "xslt1"
+QUERY_BINDING_XSLT2 = "xslt2"
+
+
+class SchematronInputs(BaseModel):
+    """Schematron run configuration resolved by Django for the container.
+
+    Everything the container needs without database access: the author's
+    rules inline (the SHACL ``shapes_text`` pattern — a ``.sch`` is a text
+    document, typically tens to hundreds of KB) and the D8 resource limits
+    (already clamped Django-side; re-clamped in the container).
+    """
+
+    schematron_text: str = Field(
+        description=(
+            "The Schematron source (.sch) to compile and run, resolved from "
+            "the step's Ruleset by Django. The container compiles it with "
+            "the SchXslt2 transpiler baked into the image."
+        ),
+    )
+    schematron_sha256: str = Field(
+        default="",
+        description=(
+            "sha256 of schematron_text, computed by Django at dispatch — "
+            "the provenance identity of the rules this run executed."
+        ),
+    )
+
+    # ── D8 resource limits (clamped Django-side; re-clamped in container) ──
+    max_input_bytes: int = Field(default=10_000_000, gt=0)
+    max_input_depth: int = Field(default=200, gt=0)
+    xslt_timeout_seconds: int = Field(default=60, gt=0)
+    max_memory_mb: int = Field(default=512, gt=0)
+    max_findings: int = Field(default=500, gt=0)
+
+    model_config = {"extra": "forbid"}
+
+
+class SchematronFinding(BaseModel):
+    """One active SVRL finding with the detail Django needs for D10.
+
+    Both ``svrl:failed-assert`` and ``svrl:successful-report`` entries are
+    active findings (a ``<report>`` can carry a publisher-authored error).
+    ``rule_id`` is the rule's native identifier (``BR-CO-15``,
+    ``PEPPOL-EN16931-R010``) and becomes ``ValidationFinding.code`` in
+    Django; ``location_xpath`` preserves the SVRL ``@location`` so the
+    finding can point at the offending element. ``flag``/``role`` carry the
+    raw SVRL attributes for provenance (severity was resolved from them via
+    the @flag → @role → fail-closed-ERROR chain, D3).
+    """
+
+    rule_id: str = Field(default="", description="Native rule id (@id).")
+    message: str = Field(description="Human-readable finding text.")
+    severity: str = Field(description="ERROR | WARNING | INFO (resolved).")
+    location_xpath: str = Field(
+        default="",
+        description="SVRL @location XPath into the submitted document.",
+    )
+    flag: str = Field(default="", description="Raw SVRL @flag attribute.")
+    role: str = Field(default="", description="Raw SVRL @role attribute.")
+
+    model_config = {"extra": "forbid"}
+
+
+class SchematronOutputs(BaseModel):
+    """Schematron results: engine status, SVRL summary, and provenance.
+
+    The signal fields (``passed`` … ``engine``) mirror the catalog entries in
+    the Django Schematron ``ValidatorConfig`` — Django's
+    ``extract_output_signals`` pulls exactly those keys for CEL assertion
+    evaluation.
+
+    D9 contract: when ``engine_status != "ok"`` the run never evaluated the
+    rules — ``passed`` is ``None`` (*unknown*, not failed), the counts are
+    meaningless, and ``finding_rule_ids_by_severity``/``findings`` stay
+    empty. Django surfaces one reserved infrastructure finding instead.
+    """
+
+    # ── D9 engine status ──
+    engine_status: str = Field(
+        default=ENGINE_STATUS_OK,
+        description="ok | error | timeout — findings only meaningful on ok.",
+    )
+    engine_message: str = Field(
+        default="",
+        description="Human-readable engine failure detail (when not ok).",
+    )
+    engine_error_code: str = Field(
+        default="",
+        description=(
+            "Machine hint for the failure kind (e.g. rules_invalid, "
+            "backend_unavailable); maps to Django's reserved codes."
+        ),
+    )
+
+    # ── o.* signals (must stay aligned with the ValidatorConfig catalog) ──
+    passed: bool | None = Field(
+        default=None,
+        description=(
+            "True iff zero ERROR-level findings; None (unknown) when the "
+            "engine could not run."
+        ),
+    )
+    error_count: int = Field(default=0, ge=0)
+    warning_count: int = Field(default=0, ge=0)
+    info_count: int = Field(default=0, ge=0)
+    # svrl:fired-rule counts rules/contexts EVALUATED, not assertions that
+    # fired — never surface this as an "assertion count" (D3 SVRL note).
+    fired_rule_count: int = Field(default=0, ge=0)
+    finding_rule_ids_by_severity: dict[str, str] = Field(
+        default_factory=dict,
+        description=(
+            'Map of native rule id to resolved severity, e.g. {"BR-CO-15": '
+            '"ERROR"}. Key membership + severity gates in CEL (D2).'
+        ),
+    )
+
+    # ── Findings (volume-capped, never silently — D10) ──
+    findings: list[SchematronFinding] = Field(
+        default_factory=list,
+        description=(
+            "Active findings (failed-asserts AND successful-reports), "
+            "capped at max_findings ordered ERROR → WARNING → INFO."
+        ),
+    )
+    findings_truncated: bool = Field(
+        default=False,
+        description="True when the findings list was capped.",
+    )
+    findings_suppressed_count: int = Field(
+        default=0,
+        ge=0,
+        description="How many findings the cap suppressed (counts stay full).",
+    )
+
+    # ── Provenance of the executed rules + engine (D5) ──
+    schematron_sha256: str = Field(
+        default="",
+        description="sha256 of the Schematron source that was executed.",
+    )
+    query_binding: str = Field(
+        default="",
+        description=(
+            "Query binding detected from the .sch root (xslt1/xslt2/…), "
+            "echoed for provenance."
+        ),
+    )
+    engine: str = Field(
+        default="",
+        description="Engine name + version that ran, e.g. 'SaxonC-HE 12.9'.",
+    )
+
+    execution_seconds: float = Field(default=0.0, ge=0)
+
+    model_config = {"extra": "forbid"}
+
+
+class SchematronInputEnvelope(ValidationInputEnvelope):
+    """Input envelope for Schematron validator containers."""
+
+    inputs: SchematronInputs
+
+
+class SchematronOutputEnvelope(ValidationOutputEnvelope):
+    """Output envelope from Schematron validator containers.
+
+    ``outputs`` can be ``None`` for runtime-failure cases where the backend
+    crashed before producing even an engine-status summary.
+    """
+
+    outputs: SchematronOutputs | None = None
+
+
+def build_schematron_input_envelope(
+    *,
+    run_id: str,
+    validator,
+    org_id: str,
+    org_name: str,
+    workflow_id: str,
+    step_id: str,
+    step_name: str | None,
+    submission_uri: str,
+    inputs: SchematronInputs,
+    callback_url: str,
+    execution_bundle_uri: str,
+    callback_id: str | None = None,
+    skip_callback: bool = False,
+) -> SchematronInputEnvelope:
+    """Build a ``SchematronInputEnvelope`` from Django validation data.
+
+    Args:
+        run_id: ValidationRun ID.
+        validator: Validator-like object (id/validation_type/version attrs).
+        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://).
+        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.
+        callback_id: Idempotency key echoed back in the callback.
+        skip_callback: True for synchronous (Docker) execution.
+    """
+    input_files = [
+        InputFileItem(
+            name="submission.xml",
+            mime_type=SupportedMimeType.APPLICATION_XML,
+            role="primary-model",
+            uri=submission_uri,
+        ),
+    ]
+
+    context = ExecutionContext(
+        callback_id=callback_id,
+        callback_url=callback_url,
+        execution_bundle_uri=execution_bundle_uri,
+        skip_callback=skip_callback,
+    )
+
+    return SchematronInputEnvelope(
+        run_id=run_id,
+        validator=ValidatorInfo(
+            id=str(validator.id),
+            type=ValidatorType(validator.validation_type),
+            version=str(getattr(validator, "version", "1")),
+        ),
+        org={"id": org_id, "name": org_name},
+        workflow={
+            "id": workflow_id,
+            "step_id": step_id,
+            "step_name": step_name,
+        },
+        input_files=input_files,
+        inputs=inputs,
+        context=context,
+    )

validibot_shared-0.12.0/validibot_shared/schematron/svrl.py

@@ -0,0 +1,277 @@
+"""SVRL report parsing — findings + signal summary (ADR-2026-07-01, D3/D10).
+
+SVRL (Schematron Validation Report Language, ISO/IEC 19757-3) is the XML
+report a Schematron run produces. This module parses an SVRL document into a
+:class:`SvrlSummary`: the individual findings plus the aggregate counts and
+the ``finding_rule_ids_by_severity`` map that feed the validator's ``o.*``
+signal surface.
+
+Design rules carried from the ADR:
+
+- **Both ``svrl:failed-assert`` and ``svrl:successful-report`` are active
+  findings**, handled identically. A ``<report>`` can carry a
+  publisher-authored error, so the element type must never drive severity.
+- **Severity resolves ``@flag`` → ``@role`` → fail-closed ``ERROR``.**
+  ``fatal``/``error`` → ERROR, ``warning``/``warn`` → WARNING,
+  ``info``/``information`` → INFO. A finding with neither attribute is
+  fail-closed to ERROR and logged for pack-curation review — nothing
+  publisher-authored is silently downgraded.
+- **``svrl:fired-rule`` counts rules/contexts evaluated**, *not* assertions
+  that fired — surfaced as ``fired_rule_count``, never an "assertion count".
+- **Findings are volume-capped, never silently** (D10): when a document blows
+  ``max_findings`` the parser keeps the first N ordered ERROR → WARNING →
+  INFO (document order within a severity) and reports how many were
+  suppressed. The caller renders the explicit truncation finding.
+
+This is the CANONICAL parser for the whole pipeline: the validator backend
+container parses Saxon's SVRL with it to build ``SchematronOutputs``, and the
+Django app re-exports it (``validibot.validations.validators.schematron.svrl``)
+for its fixture/round-trip tests. It lives beside the envelope models because
+it defines the same protocol boundary — SVRL in, the D2 signal contract out.
+Deliberately framework-free: plain-string severities, ``defusedxml``-only
+parsing, no Django.
+
+Different Schematron compilers emit slightly different SVRL dialects; parsing
+is defensive (namespace-tolerant, attribute-tolerant) and covered by the
+unit tests in this repo.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+
+from defusedxml import ElementTree as SafeET
+from defusedxml.common import (
+    DTDForbidden,
+    EntitiesForbidden,
+    ExternalReferenceForbidden,
+)
+
+logger = logging.getLogger(__name__)
+
+# The SVRL namespace from ISO/IEC 19757-3. Some tools emit un-namespaced
+# SVRL; matching is namespace-tolerant (see _local_name).
+SVRL_NS = "http://purl.oclc.org/dsdl/svrl"
+
+# Plain-string severities (shared-envelope compatible; Django maps them to
+# its own Severity enum in validator.py).
+SEVERITY_ERROR = "ERROR"
+SEVERITY_WARNING = "WARNING"
+SEVERITY_INFO = "INFO"
+
+# Rank used both for the "most severe wins" duplicate-rule-id rule and the
+# ERROR → WARNING → INFO truncation ordering (D10).
+_SEVERITY_RANK = {SEVERITY_ERROR: 0, SEVERITY_WARNING: 1, SEVERITY_INFO: 2}
+
+# @flag / @role values → severity. Lowercased before lookup.
+_SEVERITY_FROM_ATTR = {
+    "fatal": SEVERITY_ERROR,
+    "error": SEVERITY_ERROR,
+    "warning": SEVERITY_WARNING,
+    "warn": SEVERITY_WARNING,
+    "info": SEVERITY_INFO,
+    "information": SEVERITY_INFO,
+}
+
+# Default findings cap — mirrors SCHEMATRON_MAX_FINDINGS in security.py
+# (kept as a literal here so this module stays import-light and pure).
+DEFAULT_MAX_FINDINGS = 500
+
+
+class SvrlParseError(ValueError):
+    """Raised when SVRL content cannot be parsed as XML."""
+
+
+@dataclass(frozen=True)
+class SvrlFinding:
+    """One active SVRL finding (a failed assert or a successful report).
+
+    ``rule_id`` is the publisher's native identifier (``BR-CO-15``,
+    ``PEPPOL-EN16931-R010``, or a fixture's ``VB-*`` id) taken from the
+    element's ``@id``; it becomes ``ValidationFinding.code`` downstream (D10).
+    ``flag`` and ``role`` carry the raw attributes for provenance.
+    """
+
+    rule_id: str
+    message: str
+    severity: str  # SEVERITY_ERROR | SEVERITY_WARNING | SEVERITY_INFO
+    location: str = ""  # SVRL @location XPath into the submitted document
+    flag: str = ""
+    role: str = ""
+    element: str = ""  # "failed-assert" | "successful-report"
+
+
+@dataclass
+class SvrlSummary:
+    """Parsed SVRL: findings plus the aggregate ``o.*`` signal values.
+
+    ``finding_rule_ids_by_severity`` is the D2-pinned CEL map contract:
+    ``{rule_id: severity_string}`` so ``"BR-CO-15" in o.finding_rule_ids_by_severity``
+    is key membership and ``o.finding_rule_ids_by_severity["BR-CO-15"] == "ERROR"``
+    is a severity-aware gate. When one rule id fires at several severities,
+    the most severe wins.
+    """
+
+    findings: list[SvrlFinding] = field(default_factory=list)
+    error_count: int = 0
+    warning_count: int = 0
+    info_count: int = 0
+    fired_rule_count: int = 0
+    finding_rule_ids_by_severity: dict[str, str] = field(default_factory=dict)
+    findings_truncated: bool = False
+    findings_suppressed_count: int = 0
+
+    @property
+    def passed(self) -> bool:
+        """A Schematron run passes iff there are no ERROR-level findings (D3)."""
+        return self.error_count == 0
+
+
+def parse_svrl(
+    svrl_content: str | bytes,
+    *,
+    max_findings: int = DEFAULT_MAX_FINDINGS,
+) -> SvrlSummary:
+    """Parse an SVRL document into findings + the signal summary.
+
+    Args:
+        svrl_content: The SVRL report as produced by a Schematron run
+            (lxml.isoschematron for XSLT-1.0 fixtures; Saxon in production).
+        max_findings: Volume cap (D8/D10). The kept findings are the first N
+            ordered ERROR → WARNING → INFO; the summary records how many were
+            suppressed so the caller can surface an explicit truncation
+            finding — truncation is never silent.
+
+    Raises:
+        SvrlParseError: If the content is empty or not well-formed XML.
+            SVRL comes from our own engine, but defusedxml is used anyway as
+            defence in depth.
+    """
+    if not svrl_content or not str(svrl_content).strip():
+        raise SvrlParseError("Empty SVRL content.")
+
+    raw = (
+        svrl_content.encode("utf-8") if isinstance(svrl_content, str) else svrl_content
+    )
+    try:
+        root = SafeET.fromstring(raw, forbid_dtd=True)
+    except (EntitiesForbidden, ExternalReferenceForbidden, DTDForbidden) as exc:
+        raise SvrlParseError(
+            "SVRL contains forbidden constructs (entities/DTD).",
+        ) from exc
+    except SafeET.ParseError as exc:
+        raise SvrlParseError(f"Invalid SVRL XML: {exc}") from exc
+
+    summary = SvrlSummary()
+    all_findings: list[SvrlFinding] = []
+
+    for element in root.iter():
+        name = _local_name(element.tag)
+        if name == "fired-rule":
+            summary.fired_rule_count += 1
+        elif name in ("failed-assert", "successful-report"):
+            all_findings.append(_parse_finding(element, name))
+
+    # Aggregate counts + the rule-id map over ALL findings (pre-cap): the
+    # signal surface must reflect the true totals even when the persisted
+    # findings list is truncated.
+    for finding in all_findings:
+        if finding.severity == SEVERITY_ERROR:
+            summary.error_count += 1
+        elif finding.severity == SEVERITY_WARNING:
+            summary.warning_count += 1
+        else:
+            summary.info_count += 1
+
+        if finding.rule_id:
+            existing = summary.finding_rule_ids_by_severity.get(finding.rule_id)
+            if (
+                existing is None
+                or _SEVERITY_RANK[finding.severity] < _SEVERITY_RANK[existing]
+            ):
+                summary.finding_rule_ids_by_severity[finding.rule_id] = finding.severity
+        else:
+            logger.warning(
+                "SVRL %s finding has no @id; kept without a rule id (message=%r)",
+                finding.element,
+                finding.message[:120],
+            )
+
+    # Volume cap (D10): keep ERROR findings first, then WARNING, then INFO,
+    # preserving document order within each severity band.
+    if max_findings > 0 and len(all_findings) > max_findings:
+        ordered = sorted(
+            all_findings,
+            key=lambda f: _SEVERITY_RANK[f.severity],
+        )
+        summary.findings = ordered[:max_findings]
+        summary.findings_truncated = True
+        summary.findings_suppressed_count = len(all_findings) - max_findings
+        logger.warning(
+            "SVRL findings truncated: kept %d of %d (cap=%d)",
+            max_findings,
+            len(all_findings),
+            max_findings,
+        )
+    else:
+        summary.findings = all_findings
+
+    return summary
+
+
+def _parse_finding(element, element_name: str) -> SvrlFinding:
+    """Map one failed-assert / successful-report element to a finding.
+
+    Severity resolution is the D3 chain: ``@flag`` first, then ``@role``,
+    then fail-closed to ERROR with a log line for pack-curation review.
+    """
+    flag = (element.get("flag") or "").strip()
+    role = (element.get("role") or "").strip()
+
+    severity = _SEVERITY_FROM_ATTR.get(flag.lower())
+    if severity is None:
+        severity = _SEVERITY_FROM_ATTR.get(role.lower())
+    if severity is None:
+        severity = SEVERITY_ERROR
+        rule_id_for_log = (element.get("id") or "").strip()
+        logger.warning(
+            "SVRL %s (id=%r) has no recognisable @flag/@role "
+            "(flag=%r, role=%r); fail-closed to ERROR",
+            element_name,
+            rule_id_for_log,
+            flag,
+            role,
+        )
+
+    return SvrlFinding(
+        rule_id=(element.get("id") or "").strip(),
+        message=_finding_text(element),
+        severity=severity,
+        location=(element.get("location") or "").strip(),
+        flag=flag,
+        role=role,
+        element=element_name,
+    )
+
+
+def _finding_text(element) -> str:
+    """Extract the human-readable message from a finding's svrl:text child.
+
+    Joins all descendant text of every ``svrl:text`` child (publisher
+    messages may contain inline markup like ``<emph>``), collapsing internal
+    whitespace — SVRL text is authored with layout newlines that mean nothing.
+    """
+    parts: list[str] = []
+    for child in element:
+        if _local_name(child.tag) == "text":
+            parts.append(" ".join("".join(child.itertext()).split()))
+    return " ".join(p for p in parts if p).strip()
+
+
+def _local_name(tag: object) -> str:
+    """Strip any XML namespace from a tag name (namespace-tolerant matching)."""
+    text = str(tag)
+    if text.startswith("{"):
+        return text.split("}", 1)[1]
+    return text

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

@@ -143,6 +143,7 @@ class ValidatorType(str, Enum):
     BASIC = "BASIC"
     JSON_SCHEMA = "JSON_SCHEMA"
     XML_SCHEMA = "XML_SCHEMA"
+    SCHEMATRON = "SCHEMATRON"
     SHACL = "SHACL"
     ENERGYPLUS = "ENERGYPLUS"
     FMU = "FMU"