← Files LuciaARCHIVED FILE

modules/deep-research-validator/scripts/evidence_refs.py

9.96 KB · Nov 21, 2026 · 00:11 UTC

↓ Download file

"""Verify evidence bytes and locators; never infer relevance or legal support."""

from __future__ import annotations

import argparse
import hashlib
import json
import re
import sys
from pathlib import Path
from typing import Any

__all__ = [
    "read_capture",
    "validate_reference",
    "reference_value",
    "verify_answer_identity",
    "make_reference",
    "main",
]

REFERENCE_KINDS = {
    "source_capture",
    "source_access",
    "fact",
    "scope",
    "calculation",
    "claim",
    "answer",
    "answer_contract",
    "inspection_note",
    "treatment_note",
}


class EvidenceDigestError(ValueError):
    """The retained bytes differ from the expected revision."""


def _file(root: Path, relative: object) -> Path:
    if (
        not isinstance(relative, str)
        or not relative
        or Path(relative).is_absolute()
        or ".." in Path(relative).parts
    ):
        raise ValueError("Evidence reference requires a safe relative artifact path")
    candidate = root.resolve()
    for part in Path(relative).parts:
        candidate /= part
        if candidate.is_symlink():
            raise ValueError("Symlink evidence artifact rejected")
    path = candidate.resolve(strict=True)
    if not path.is_relative_to(root.resolve()) or not path.is_file():
        raise ValueError("Evidence reference escapes its run or is not a file")
    return path


def _checked_bytes(path: Path, expected: object) -> bytes:
    if not isinstance(expected, str) or not re.fullmatch(r"[0-9a-f]{64}", expected):
        raise ValueError(f"Evidence digest missing or invalid: {path.name}")
    raw = path.read_bytes()
    if hashlib.sha256(raw).hexdigest() != expected:
        raise EvidenceDigestError(f"Evidence artifact digest mismatch: {path.name}")
    return raw


def read_capture(source: dict[str, Any], base: Path | None) -> tuple[str, str, str]:
    """Check retained original and extracted bytes before consuming source text."""
    text_path = source.get("captured_text_path")
    original_path = source.get("captured_original_path")
    scope = str(source.get("capture_scope") or "captured_text")
    if not text_path and not original_path:
        return str(source.get("excerpt") or ""), "inventory_excerpt", "excerpt_only"
    if base is None:
        return "", scope, "capture_base_missing"
    try:
        if original_path:
            _checked_bytes(
                _file(base, original_path), source.get("source_bytes_sha256")
            )
        if not text_path:
            return "", scope, "verified_metadata_only"
        raw = _checked_bytes(
            _file(base, text_path), source.get("extracted_text_sha256")
        )
        return raw.decode("utf-8"), scope, "verified"
    except UnicodeDecodeError:
        return "", scope, "invalid_capture_encoding"
    except FileNotFoundError:
        return "", scope, "capture_missing"
    except EvidenceDigestError:
        return "", scope, "digest_mismatch"
    except ValueError:
        return "", scope, "capture_reference_invalid"
    except OSError:
        return "", scope, "capture_unreadable"


def _pointer(value: Any, pointer: object) -> Any:
    if not isinstance(pointer, str) or (pointer and not pointer.startswith("/")):
        raise ValueError("Evidence JSON pointer must identify an existing value")
    if not pointer:
        return value
    for token in pointer[1:].split("/"):
        if re.search(r"~(?![01])", token):
            raise ValueError("Invalid JSON pointer escape")
        token = token.replace("~1", "/").replace("~0", "~")
        if isinstance(value, dict) and token in value:
            value = value[token]
        elif (
            isinstance(value, list)
            and re.fullmatch(r"0|[1-9][0-9]*", token)
            and int(token) < len(value)
        ):
            value = value[int(token)]
        else:
            raise ValueError("Evidence JSON pointer does not resolve")
    return value


def validate_reference(root: Path, reference: object) -> list[Path]:
    """Resolve a declared reference at its pinned revision, without judging meaning."""
    if (
        not isinstance(reference, dict)
        or not isinstance(reference.get("kind"), str)
        or reference["kind"] not in REFERENCE_KINDS
    ):
        raise ValueError("Unsupported structured evidence reference")
    path = _file(root, reference.get("artifact"))
    raw = _checked_bytes(path, reference.get("sha256"))
    artifacts = [path]
    kind = reference["kind"]
    if kind == "claim":
        identifier = reference.get("claim_index")
        if type(identifier) is not int or identifier < 1:
            raise ValueError("Claim reference requires its actual claim index")
        review = json.loads(raw)
        if not isinstance(review, dict) or not isinstance(review.get("claims"), list):
            raise ValueError("Claim reference requires an actual claims review")
        matches = [
            claim
            for claim in review.get("claims", [])
            if isinstance(claim, dict) and claim.get("claim_index") == identifier
        ]
        if len(matches) != 1:
            raise ValueError("Referenced claim does not exist or is ambiguous")
    elif kind == "source_capture":
        inventory_path = _file(root, reference.get("inventory"))
        inventory_raw = _checked_bytes(
            inventory_path, reference.get("inventory_sha256")
        )
        inventory = json.loads(inventory_raw)
        if not isinstance(inventory, dict) or not isinstance(
            inventory.get("sources"), list
        ):
            raise ValueError("Source reference requires an actual source inventory")
        sources = [
            source
            for source in inventory.get("sources", [])
            if isinstance(source, dict)
            and source.get("source_id") == reference.get("source_id")
        ]
        if len(sources) != 1:
            raise ValueError("Source reference does not resolve uniquely")
        source = sources[0]
        capture_id = reference.get("capture_id")
        candidates = (
            [source]
            if source.get("capture_id") == capture_id
            else [
                item
                for item in source.get("capture_history", [])
                if isinstance(item, dict) and item.get("capture_id") == capture_id
            ]
        )
        if not isinstance(capture_id, str) or not capture_id or len(candidates) != 1:
            raise ValueError("Capture reference does not resolve uniquely")
        capture = candidates[0]
        text, _, integrity = read_capture(capture, inventory_path.parent)
        if (
            integrity != "verified"
            or _file(inventory_path.parent, capture.get("captured_text_path")) != path
        ):
            raise ValueError(
                "Source reference does not identify verified capture bytes"
            )
        artifacts.append(inventory_path)
        if capture.get("captured_original_path"):
            artifacts.append(
                _file(inventory_path.parent, capture["captured_original_path"])
            )
        _span(text, reference)
    elif kind != "answer":
        if "pointer" in reference:
            _pointer(json.loads(raw), reference["pointer"])
        else:
            _span(raw.decode("utf-8"), reference)
    return artifacts


def _span(text: str, reference: dict[str, Any]) -> None:
    start, end = reference.get("start_char"), reference.get("end_char")
    if (
        type(start) is not int
        or type(end) is not int
        or not 0 <= start < end <= len(text)
    ):
        raise ValueError("Evidence passage locator does not resolve in its capture")
    if "passage" in reference and text[start:end] != reference["passage"]:
        raise ValueError("Evidence passage differs from its pinned locator")


def reference_value(root: Path, reference: dict[str, Any]) -> Any:
    """Read a declared JSON note at its verified revision and actual pointer."""
    validate_reference(root, reference)
    raw = _checked_bytes(
        _file(root, reference.get("artifact")), reference.get("sha256")
    )
    return _pointer(json.loads(raw), reference.get("pointer"))


def verify_answer_identity(answer: Path, review: Path) -> str:
    """A review can accompany only its actual answer, not another saved revision."""
    raw = answer.read_bytes()
    value = json.loads(review.read_bytes())
    recorded = value.get("validated_document") if isinstance(value, dict) else None
    if (
        not isinstance(recorded, str)
        or not recorded.strip()
        or raw.decode("utf-8").strip() != recorded.strip()
    ):
        raise ValueError("The delivered document differs from the reviewed answer")
    return hashlib.sha256(raw).hexdigest()


def make_reference(root: Path, selection: dict[str, Any]) -> dict[str, Any]:
    """Pin hashes for a model-selected existing artifact and locator, without choosing evidence."""
    reference = dict(selection)
    reference["sha256"] = hashlib.sha256(
        _file(root, reference.get("artifact")).read_bytes()
    ).hexdigest()
    if reference.get("kind") == "source_capture":
        reference["inventory_sha256"] = hashlib.sha256(
            _file(root, reference.get("inventory")).read_bytes()
        ).hexdigest()
    validate_reference(root, reference)
    return reference


def main() -> int:
    """Return a verified reference for an explicitly selected artifact; write no run files."""
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--output-dir", type=Path, required=True)
    parser.add_argument("--selection", type=Path, required=True)
    args = parser.parse_args()
    try:
        root = args.output_dir.resolve(strict=True)
        selection = json.loads(args.selection.read_bytes())
        if not isinstance(selection, dict):
            raise ValueError("Reference selection must be an object")
        result = make_reference(root, selection)
    except (OSError, ValueError) as exc:
        parser.error(str(exc))
    sys.stdout.write(json.dumps(result, ensure_ascii=False) + "\n")
    return 0


if __name__ == "__main__":
    raise SystemExit(main())

SHA-256: b47cbe13777a3cf96398ca39312ccc234557ad7a62ab654c9cccae2b498fd878