semantic-trust 0.1.0__tar.gz

semantic_trust-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ravish Jain
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

semantic_trust-0.1.0/PKG-INFO

@@ -0,0 +1,17 @@
+Metadata-Version: 2.4
+Name: semantic-trust
+Version: 0.1.0
+Summary: Score and certify dbt Semantic Layer models — trust bands, gates, and dbt-parse certification.
+Requires-Python: >=3.11
+License-File: LICENSE
+Requires-Dist: mcp>=1.0
+Provides-Extra: ci
+Requires-Dist: pytest>=8.0; extra == "ci"
+Requires-Dist: hypothesis>=6.0; extra == "ci"
+Requires-Dist: pyyaml>=6.0; extra == "ci"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: hypothesis>=6.0; extra == "dev"
+Requires-Dist: pyyaml>=6.0; extra == "dev"
+Requires-Dist: dbt-metricflow<0.14,>=0.13; extra == "dev"
+Dynamic: license-file

semantic_trust-0.1.0/README.md

@@ -0,0 +1,118 @@
+# semantic-trust
+
+Score and certify dbt Semantic Layer models. The trust/quality layer on top of authoring.
+
+---
+
+## Why
+
+dbt-labs' agent skills author semantic models — they scaffold YAML, wire measures, and generate metric definitions. `semantic-trust` picks up where authoring stops: it **scores** and **certifies** those models before they reach production.
+
+Scoring runs four deterministic gates:
+
+- **Structural** — required fields present, types correct, no dangling references.
+- **Uniqueness** — no duplicate metric or dimension names across the project.
+- **Joinability** — join paths resolve; foreign-key references match declared entities.
+- **Ownership** — every model has an approved owner email (optionally domain-restricted).
+
+On top of the gate results, an LLM-judgment pass evaluates description quality, naming clarity, and metric intent. The combined score maps to an **A–F trust band**. A model that clears all gates and passes LLM review earns an A; structural failures floor the score at F.
+
+Certification adds a final compile check via `dbt parse`. A model that scores B or above and compiles cleanly is marked **certified** and safe to promote.
+
+`semantic-trust` works on top of any dbt project — it reads the compiled `semantic_manifest.json` that `dbt parse` emits and requires no changes to your dbt project structure.
+
+---
+
+## Install
+
+### Claude Code plugin
+
+The plugin bundles the skills (`document-semantics`, `build-dbt-model`, `validate-semantics`) and declares the MCP server. The public repository and marketplace install via the Claude Code plugin registry are **coming in a future release (Phase 5)**. Once the repo is published, you'll install locally with:
+
+```bash
+git clone https://github.com/rj1224/semantic-trust
+cd semantic-trust
+# Claude Code picks up .claude-plugin/plugin.json and .mcp.json automatically
+# when you open the project in a Claude Code session.
+```
+
+### MCP server (standalone)
+
+The plugin's `.mcp.json` launches the MCP server via `uvx`. You can also start it directly:
+
+```bash
+uvx semantic-trust-mcp
+```
+
+This starts the `semantic-trust-mcp` stdio server, exposing three tools: `scaffold_semantic_model`, `score_semantic_model`, and `validate_semantic_model`.
+
+---
+
+## Quickstart
+
+Open a Claude Code session in your dbt project directory, then:
+
+**Natural language:**
+
+```
+validate my semantic model
+```
+
+Claude routes this to the `validate-semantics` skill, which compiles your project, runs all four gates, applies LLM judgment, and returns a trust report with gate results, score, trust band, and any blocking issues.
+
+**Slash commands:**
+
+```
+/semantic-trust:validate    # full trust report
+/semantic-trust:document    # generate or improve semantic model descriptions
+/semantic-trust:build       # scaffold a new semantic model from a dbt model
+```
+
+The trust report shows gate-by-gate pass/fail, the A–F band, and a recommendation (promote / fix-and-retry / escalate).
+
+---
+
+## dbt version support
+
+`semantic-trust` supports both the legacy and the current dbt Semantic Layer spec:
+
+| dbt Core version | Spec form | Notes |
+|---|---|---|
+| 1.6 – 1.11 | **Legacy** — top-level `semantic_models:` block + standalone `measures:` in `schema.yml` | `mf validate-configs` available as an additional validation pass |
+| **1.12+** / Fusion | **Latest** — model-annotation form: semantic metadata lives inside `models:` blocks | `mf validate-configs` not supported (skipped automatically) |
+
+`dbt parse` is the **universal compile gate** for both versions — `semantic-trust` always runs it first. `mf validate-configs` is a legacy-only bonus pass and is skipped automatically on 1.12+ projects.
+
+The version is detected from `dbt_project.yml` at runtime; no configuration is required.
+
+---
+
+## Not affiliated with dbt Labs
+
+`semantic-trust` references the dbt ecosystem and is designed to work alongside dbt projects. It is **not** an official dbt product and is not affiliated with, endorsed by, or supported by dbt Labs, Inc.
+
+The vendored content under `vendor/dbt-agent-skills/` consists of dbt-labs' public Semantic Layer spec guides, included under their Apache-2.0 license. See `vendor/dbt-agent-skills/NOTICE` for attribution and license terms. That content remains Apache-2.0; the rest of this project is MIT.
+
+---
+
+## Configuration
+
+`semantic-trust` works with zero configuration. To enable the ownership gate's domain check, add a `.semantic-trust.json` file at your dbt project root:
+
+```json
+{
+  "approved_email_domains": ["example.com"]
+}
+```
+
+With `approved_email_domains` set, the ownership gate fails any model whose `owner.email` does not match one of the listed domains. Without this config key, the ownership gate only checks that an email is present.
+
+No other configuration keys are required or supported in 0.1.0.
+
+---
+
+## License
+
+This project is licensed under the **MIT License** — see the `LICENSE` file.
+
+Vendored content under `vendor/dbt-agent-skills/` is licensed under the **Apache-2.0 License** — see `vendor/dbt-agent-skills/NOTICE` and `vendor/dbt-agent-skills/LICENSE`.

semantic_trust-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[project]
+name = "semantic-trust"
+version = "0.1.0"
+description = "Score and certify dbt Semantic Layer models — trust bands, gates, and dbt-parse certification."
+requires-python = ">=3.11"
+dependencies = ["mcp>=1.0"]    # engine reads the compiled dbt manifest (JSON); MCP = the server SDK
+
+# Entry points (AD-1). MCP server is the skill-facing interface (launched via uvx by the plugin);
+# the `semantic-trust` console script is the local dev/testing CLI.
+[project.scripts]
+semantic-trust-mcp = "trust.mcp_server:main"
+semantic-trust = "trust.cli:main_cli"
+
+[project.optional-dependencies]
+# ci: fast CI — pytest + hypothesis + pyyaml (e2e tests render YAML). No dbt tree.
+ci = ["pytest>=8.0", "hypothesis>=6.0", "pyyaml>=6.0"]
+# dev adds the dbt-metricflow bundle for `mf validate-configs` (legacy-only) + latest-spec checks.
+dev = ["pytest>=8.0", "hypothesis>=6.0", "pyyaml>=6.0", "dbt-metricflow>=0.13,<0.14"]
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+include = ["trust*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

semantic_trust-0.1.0/semantic_trust.egg-info/PKG-INFO

@@ -0,0 +1,17 @@
+Metadata-Version: 2.4
+Name: semantic-trust
+Version: 0.1.0
+Summary: Score and certify dbt Semantic Layer models — trust bands, gates, and dbt-parse certification.
+Requires-Python: >=3.11
+License-File: LICENSE
+Requires-Dist: mcp>=1.0
+Provides-Extra: ci
+Requires-Dist: pytest>=8.0; extra == "ci"
+Requires-Dist: hypothesis>=6.0; extra == "ci"
+Requires-Dist: pyyaml>=6.0; extra == "ci"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: hypothesis>=6.0; extra == "dev"
+Requires-Dist: pyyaml>=6.0; extra == "dev"
+Requires-Dist: dbt-metricflow<0.14,>=0.13; extra == "dev"
+Dynamic: license-file

semantic_trust-0.1.0/semantic_trust.egg-info/SOURCES.txt

@@ -0,0 +1,47 @@
+LICENSE
+README.md
+pyproject.toml
+semantic_trust.egg-info/PKG-INFO
+semantic_trust.egg-info/SOURCES.txt
+semantic_trust.egg-info/dependency_links.txt
+semantic_trust.egg-info/entry_points.txt
+semantic_trust.egg-info/requires.txt
+semantic_trust.egg-info/top_level.txt
+tests/test_attribution.py
+tests/test_cli.py
+tests/test_compile.py
+tests/test_config.py
+tests/test_env_doctor.py
+tests/test_joinability.py
+tests/test_judgment.py
+tests/test_makefile_targets.py
+tests/test_manifest_loader.py
+tests/test_manifest_scaffold.py
+tests/test_mcp_server.py
+tests/test_ownership.py
+tests/test_ownership_gate.py
+tests/test_packaging.py
+tests/test_report.py
+tests/test_scorer.py
+tests/test_secrets_scan.py
+tests/test_skills_gate.py
+tests/test_spec_detect.py
+tests/test_templates_grammar.py
+tests/test_uniqueness.py
+tests/test_vendor_check.py
+tests/test_vendored_refs.py
+trust/__init__.py
+trust/cli.py
+trust/compile.py
+trust/config.py
+trust/joinability.py
+trust/judgment.py
+trust/manifest_loader.py
+trust/manifest_scaffold.py
+trust/mcp_server.py
+trust/normalized.py
+trust/ownership.py
+trust/report.py
+trust/scorer.py
+trust/spec_detect.py
+trust/uniqueness.py

semantic_trust-0.1.0/semantic_trust.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

semantic_trust-0.1.0/semantic_trust.egg-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+semantic-trust = trust.cli:main_cli
+semantic-trust-mcp = trust.mcp_server:main

semantic_trust-0.1.0/semantic_trust.egg-info/requires.txt

@@ -0,0 +1,12 @@
+mcp>=1.0
+
+[ci]
+pytest>=8.0
+hypothesis>=6.0
+pyyaml>=6.0
+
+[dev]
+pytest>=8.0
+hypothesis>=6.0
+pyyaml>=6.0
+dbt-metricflow<0.14,>=0.13

semantic_trust-0.1.0/semantic_trust.egg-info/top_level.txt

@@ -0,0 +1 @@
+trust

semantic_trust-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

semantic_trust-0.1.0/tests/test_attribution.py

@@ -0,0 +1,13 @@
+from trust.manifest_loader import load_metrics
+
+FIX = "tests/fixtures/manifests/two_model_derived"
+
+def test_simple_metrics_owned_by_their_model():
+    by = {m.name: m for m in load_metrics(FIX)}
+    assert by["order_revenue"].owner_model == "fct_orders"
+    assert by["refund_total"].owner_model == "fct_refunds"
+
+def test_derived_metric_is_cross_model_unowned():
+    by = {m.name: m for m in load_metrics(FIX)}
+    assert by["net_revenue"].owner_model is None
+    assert by["net_revenue"].type == "derived"

semantic_trust-0.1.0/tests/test_cli.py

@@ -0,0 +1,96 @@
+# tests/test_cli.py
+# AD-4: direct import, not subprocess — faster and avoids PATH/venv issues.
+from pathlib import Path
+from trust.cli import build_report, _orphan_collision_warnings
+from trust.normalized import NormalizedMetric
+
+LEGACY_FIX = str(Path(__file__).parent / "fixtures" / "manifests" / "qcommerce_legacy")
+
+
+def test_build_report_returns_band_and_gates():
+    rep = build_report(LEGACY_FIX, "orders")
+    assert rep["model"] == "orders"
+    assert rep["band"] in {"A", "B", "C", "D", "F"}
+    assert {"structural", "ownership", "completeness", "uniqueness", "joinability"} <= set(rep["gates"].keys())
+
+
+def test_build_report_unknown_model_returns_error():
+    rep = build_report(LEGACY_FIX, "nonexistent_model")
+    assert "error" in rep
+
+
+def test_orphan_name_collision_surfaces_warning():
+    """Pure unit test of _orphan_collision_warnings for the name-collision path.
+
+    Two orphan (owner_model=None) metrics that share a name must produce a
+    name-collision warning, not pass clean-and-silent.
+
+    Note: this scenario is unreachable via real dbt — dbt enforces unique metric names
+    at parse time, so a semantic_manifest.json with two metrics sharing a name can
+    never be genuine `dbt parse` output. No fixture is used here. The logic is
+    retained as defense-in-depth and is tested entirely in-memory.
+    """
+    # Construct two orphan metrics with the same name but distinct object identities.
+    metric_a = NormalizedMetric(
+        name="blended_rate",
+        type="derived",
+        definition_norm="total_order_amount / 2",
+        description="Derived metric A.",
+        owner=None,
+        source_file="models/metrics.yml",
+        owner_model=None,
+    )
+    metric_b = NormalizedMetric(
+        name="blended_rate",
+        type="derived",
+        definition_norm="total_order_amount / 3",
+        description="Derived metric B — duplicate name, also orphaned.",
+        owner=None,
+        source_file="models/metrics.yml",
+        owner_model=None,
+    )
+    all_metrics = [metric_a, metric_b]
+    # Collision dict as find_collisions would produce for a name collision.
+    collisions = [
+        {
+            "kind": "name",
+            "a": "blended_rate",
+            "b": "blended_rate",
+            "files": ["models/metrics.yml", "models/metrics.yml"],
+        }
+    ]
+    warnings = _orphan_collision_warnings(all_metrics, collisions)
+    assert any(
+        "blended_rate" in w and "name collision" in w for w in warnings
+    ), f"expected a name-collision warning for blended_rate, got: {warnings}"
+
+
+def test_build_report_is_two_level_and_deterministic():
+    LATEST_FIX = str(Path(__file__).parent / "fixtures" / "manifests" / "qcommerce_latest")
+    a = build_report(LATEST_FIX, "orders")
+    b = build_report(LATEST_FIX, "orders")
+    assert a == b                                   # reproducible
+    assert "documents" in a and "trust_score" in a and a["band"] in {"A", "B", "C", "D", "F"}
+
+
+def test_build_report_joinability_sees_all_models():
+    """build_report must pass ALL models in the project to the joinability gate,
+    not just the target model (so cross-model join checks are meaningful).
+    The joinbreak fixture has a parity mismatch — gate must fail, not pass silently."""
+    JOINBREAK_FIX = str(Path(__file__).parent / "fixtures" / "manifests" / "qcommerce_joinbreak")
+    rep = build_report(JOINBREAK_FIX, "orders")
+    assert "joinability" in rep["gates"]
+    # Joinability MUST fail — orders has a parity mismatch with payments
+    assert rep["gates"]["joinability"] is False, (
+        "joinability gate should be False for joinbreak fixture, "
+        f"got gates={rep['gates']}"
+    )
+
+
+def test_build_report_two_level_mcp_shape():
+    """MCP handler must return the same two-level dict as build_report."""
+    from trust.mcp_server import handle_score_semantic_model
+    LATEST_FIX = str(Path(__file__).parent / "fixtures" / "manifests" / "qcommerce_latest")
+    rep = handle_score_semantic_model(LATEST_FIX, "orders")
+    assert "documents" in rep and "trust_score" in rep
+    assert rep["band"] in {"A", "B", "C", "D", "F"}

semantic_trust-0.1.0/tests/test_compile.py

@@ -0,0 +1,18 @@
+import os
+from unittest import mock
+from trust import compile as compile_mod
+
+def test_compile_ok_when_parse_succeeds_and_artifact_exists(tmp_path):
+    (tmp_path / "target").mkdir()
+    (tmp_path / "target" / "semantic_manifest.json").write_text("{}")
+    fake = mock.Mock(returncode=0, stdout="ok", stderr="")
+    with mock.patch("trust.compile.subprocess.run", return_value=fake):
+        res = compile_mod.compile_manifest(str(tmp_path))
+    assert res["ok"] is True
+    assert res["manifest_path"].endswith("target/semantic_manifest.json")
+
+def test_compile_not_ok_when_artifact_absent(tmp_path):
+    fake = mock.Mock(returncode=0, stdout="", stderr="")
+    with mock.patch("trust.compile.subprocess.run", return_value=fake):
+        res = compile_mod.compile_manifest(str(tmp_path))
+    assert res["ok"] is False

semantic_trust-0.1.0/tests/test_config.py

@@ -0,0 +1,44 @@
+"""
+Tests for trust.config.load_config — safe defaults and JSON parsing.
+"""
+import json
+import os
+from trust.config import load_config
+
+
+def test_missing_config_safe_default(tmp_path):
+    """No config file → empty approved_email_domains (no domain check, not a failure)."""
+    cfg = load_config(str(tmp_path))
+    assert cfg["approved_email_domains"] == []
+
+
+def test_config_with_domains_loaded(tmp_path):
+    """Valid JSON with approved_email_domains → list returned correctly."""
+    config_file = tmp_path / ".semantic-trust.json"
+    config_file.write_text(json.dumps({"approved_email_domains": ["example.com", "corp.io"]}))
+    cfg = load_config(str(tmp_path))
+    assert cfg["approved_email_domains"] == ["example.com", "corp.io"]
+
+
+def test_config_missing_key_returns_empty_list(tmp_path):
+    """JSON present but key absent → safe default empty list."""
+    config_file = tmp_path / ".semantic-trust.json"
+    config_file.write_text(json.dumps({"some_other_key": "value"}))
+    cfg = load_config(str(tmp_path))
+    assert cfg["approved_email_domains"] == []
+
+
+def test_config_empty_file_returns_empty_list(tmp_path):
+    """Empty/invalid JSON file → safe default."""
+    config_file = tmp_path / ".semantic-trust.json"
+    config_file.write_text("")
+    cfg = load_config(str(tmp_path))
+    assert cfg["approved_email_domains"] == []
+
+
+def test_no_hardcoded_domains(tmp_path):
+    """load_config must never inject any domain when file is absent."""
+    cfg = load_config(str(tmp_path))
+    # Explicitly verify no domain leaks from implementation
+    assert cfg["approved_email_domains"] == []
+    assert len(cfg["approved_email_domains"]) == 0

semantic_trust-0.1.0/tests/test_env_doctor.py

@@ -0,0 +1,14 @@
+from scripts.env_doctor import check, HARD
+
+
+def test_check_reports_hard_requirements():
+    rows = check()
+    names = {n for n, _, _ in rows}
+    assert HARD <= names                      # every hard req is checked
+    assert "python>=3.11" in names and "uv" in names and "pyyaml" in names
+
+
+def test_python_and_pyyaml_present_in_this_env():
+    rows = {n: ok for n, ok, _ in check()}
+    assert rows["python>=3.11"] is True        # run under uv's 3.12
+    assert rows["pyyaml"] is True              # installed via .[dev]

semantic_trust-0.1.0/tests/test_joinability.py

@@ -0,0 +1,59 @@
+# tests/test_joinability.py
+from trust.manifest_loader import load_models, load_metrics
+from trust.joinability import check_joinability
+from trust.uniqueness import find_collisions
+from trust.scorer import score_model
+
+
+def test_parity_mismatch_flagged():
+    models = load_models("tests/fixtures/manifests/joinbreak")
+    issues = check_joinability(models)
+    assert any(i.rule == "joinability_parity" for i in issues)
+
+
+def test_clean_project_no_joinability_issues():
+    models = load_models("tests/fixtures/manifests/single_latest")
+    assert check_joinability(models) == []
+
+
+def test_orphan_or_parity_entity_flagged():
+    models = load_models("tests/fixtures/manifests/joinbreak")
+    issues = check_joinability(models)
+    assert any(i.rule == "joinability_orphan" for i in issues)
+    assert any(i.rule == "joinability_parity" for i in issues)
+
+
+def test_joinability_issues_have_correct_fields():
+    models = load_models("tests/fixtures/manifests/joinbreak")
+    issues = check_joinability(models)
+    for issue in issues:
+        assert issue.severity == "warning"
+        assert issue.provenance == "deterministic"
+        assert issue.rule in {"joinability_parity", "joinability_orphan"}
+        assert issue.location
+
+
+def test_joinability_gate_wired_into_scorer():
+    models = load_models("tests/fixtures/manifests/joinbreak")
+    j_issues = check_joinability(models)
+    sm = next(m for m in models if m.name == "fct_orders")
+    model_j_issues = [i for i in j_issues if i.location == sm.source_file]
+    metrics = load_metrics("tests/fixtures/manifests/joinbreak")
+    model_metrics = [m for m in metrics if m.owner_model == sm.name]
+    collisions = find_collisions(metrics)
+    rep = score_model(sm, model_metrics, collisions, joinability_issues=model_j_issues)
+    assert "joinability" in rep.gates
+    assert rep.gates["joinability"] is False
+    assert rep.band == "F"
+
+
+def test_clean_project_joinability_gate_passes():
+    models = load_models("tests/fixtures/manifests/single_latest")
+    j_issues = check_joinability(models)
+    assert j_issues == []
+    sm = next(m for m in models if m.name == "fct_orders")
+    metrics = load_metrics("tests/fixtures/manifests/single_latest")
+    model_metrics = [m for m in metrics if m.owner_model == sm.name]
+    collisions = find_collisions(metrics)
+    rep = score_model(sm, model_metrics, collisions, joinability_issues=j_issues)
+    assert rep.gates["joinability"] is True

semantic_trust-0.1.0/tests/test_judgment.py

@@ -0,0 +1,128 @@
+"""
+Tests for trust/judgment.py — judgment combination + guardrail (Task 3.1d).
+
+Guardrail contract:
+  apply_judgment() accepts the deterministic ModelReport (read-only) and an LLM
+  judgment payload (per judge.md) and returns a NEW ModelReport that:
+    - adds document_quality per DocumentReport (from judgment["documents"])
+    - appends provenance="llm_judge" advisory issues per DocumentReport
+    - NEVER changes trust_score, band, gates, context, quality, or any
+      provenance="deterministic" issue regardless of what the payload contains
+"""
+from trust.scorer import score_model
+from trust.manifest_loader import load_models, load_metrics
+from trust.uniqueness import find_collisions
+from trust.judgment import apply_judgment
+
+
+def _report():
+    FIX = "tests/fixtures/manifests/qcommerce_latest"
+    sm = next(m for m in load_models(FIX) if m.name == "orders")
+    ms = load_metrics(FIX)
+    return score_model(sm, [m for m in ms if m.owner_model == "orders"], find_collisions(ms))
+
+
+def test_judgment_adds_quality_without_touching_trust():
+    base = _report()
+    before = (base.trust_score, base.band, dict(base.gates))
+    out = apply_judgment(base, {"documents": {"metrics": {"quality": 62, "issues": [
+        {"severity": "warning", "dimension": "data_context", "rule": "description_business_meaning",
+         "message": "restates the formula", "location": "metrics[0].description"}]}}})
+    assert (out.trust_score, out.band, dict(out.gates)) == before          # deterministic untouched
+    assert out.documents["metrics"].to_dict().get("document_quality") == 62
+    assert any(i["provenance"] == "llm_judge" for i in out.documents["metrics"].to_dict()["issues"])
+
+
+def test_judgment_cannot_flip_a_gate():
+    base = _report()
+    out = apply_judgment(base, {"override_gates": {"uniqueness": False}, "documents": {}})  # malicious payload
+    assert out.gates == base.gates                                          # ignored
+
+
+def test_judgment_does_not_mutate_base_report():
+    """apply_judgment must return a new object; the original is unchanged."""
+    base = _report()
+    base_trust = base.trust_score
+    base_metrics_issues_count = len(base.documents["metrics"].issues)
+    apply_judgment(base, {"documents": {"metrics": {"quality": 50, "issues": [
+        {"severity": "info", "dimension": "data_context", "rule": "some_rule",
+         "message": "advisory note", "location": "metrics[0]"}]}}})
+    assert base.trust_score == base_trust
+    assert len(base.documents["metrics"].issues) == base_metrics_issues_count
+
+
+def test_judgment_no_documents_key_is_safe():
+    """Payload with no 'documents' key must not raise — treat as empty."""
+    base = _report()
+    out = apply_judgment(base, {})
+    assert out.trust_score == base.trust_score
+    assert out.band == base.band
+
+
+def test_judgment_unknown_doc_key_ignored():
+    """LLM referencing a non-existent document name must not raise or corrupt."""
+    base = _report()
+    out = apply_judgment(base, {"documents": {"nonexistent_doc": {"quality": 99, "issues": []}}})
+    assert out.trust_score == base.trust_score
+    # known documents unchanged
+    for key in base.documents:
+        assert out.documents[key].to_dict().get("document_quality") is None
+
+
+def test_judgment_deterministic_issues_provenance_unchanged():
+    """Deterministic issues on the base report keep provenance='deterministic' after apply_judgment."""
+    base = _report()
+    # inject a synthetic deterministic issue onto the base (simulate scorer output)
+    from trust.report import Issue
+    synth = Issue(severity="warning", dimension="completeness", rule="test_rule",
+                  message="test", location="x.yml", provenance="deterministic")
+    base.issues.append(synth)
+    out = apply_judgment(base, {"documents": {}})
+    det_issues = [i for i in out.issues if i.provenance == "deterministic"]
+    assert any(i.rule == "test_rule" for i in det_issues)
+
+
+def test_quality_clamped_above_100():
+    """LLM emitting quality > 100 must be clamped to 100."""
+    base = _report()
+    out = apply_judgment(base, {"documents": {"metrics": {"quality": 150, "issues": []}}})
+    assert out.documents["metrics"].document_quality == 100
+
+
+def test_quality_clamped_below_0():
+    """LLM emitting negative quality must be clamped to 0."""
+    base = _report()
+    out = apply_judgment(base, {"documents": {"metrics": {"quality": -50, "issues": []}}})
+    assert out.documents["metrics"].document_quality == 0
+
+
+def test_quality_none_leaves_document_quality_unset():
+    """Missing quality key must not crash and must leave document_quality as None."""
+    base = _report()
+    out = apply_judgment(base, {"documents": {"metrics": {"issues": []}}})
+    assert out.documents["metrics"].document_quality is None
+
+
+def test_quality_non_int_leaves_document_quality_unset():
+    """Non-int/unconvertible quality must not crash; document_quality stays None."""
+    base = _report()
+    out = apply_judgment(base, {"documents": {"metrics": {"quality": "bad_value", "issues": []}}})
+    assert out.documents["metrics"].document_quality is None
+
+
+def test_deterministic_provenance_on_doc_issue_retained_after_llm_append():
+    """A deterministic issue on a DocumentReport retains its provenance after apply_judgment
+    appends an llm_judge issue to the same document (deep-copy guarantee)."""
+    from trust.report import Issue
+    base = _report()
+    det_issue = Issue(severity="warning", dimension="completeness", rule="det_rule",
+                      message="deterministic", location="metrics.yml", provenance="deterministic")
+    base.documents["metrics"].issues.append(det_issue)
+    out = apply_judgment(base, {"documents": {"metrics": {"quality": 70, "issues": [
+        {"severity": "info", "dimension": "data_context", "rule": "llm_rule",
+         "message": "advisory", "location": "metrics[0]"}]}}})
+    doc_issues = out.documents["metrics"].issues
+    det_issues = [i for i in doc_issues if i.provenance == "deterministic"]
+    llm_issues = [i for i in doc_issues if i.provenance == "llm_judge"]
+    assert any(i.rule == "det_rule" for i in det_issues), "deterministic issue lost"
+    assert any(i.rule == "llm_rule" for i in llm_issues), "llm_judge issue missing"