PTSIP 0.3.1__py3-none-any.whl

ptsip/app/service.py

@@ -0,0 +1,285 @@
+from __future__ import annotations
+
+from typing import Any
+
+from ..clarification.resolution import dump_payload, load_profile_text, parse_answer, project_payload, validate_answer, validate_projected_payload
+from ..clarification.resolution.model import DecisionAnswer
+from .github_client import GitHubAppClient, GitHubAPIError
+from .store import DecisionRecord, DecisionStore
+
+WRITE_PERMISSIONS = {"admin", "maintain", "write"}
+
+
+def _answer_from_mapping(payload: dict[str, object]) -> DecisionAnswer:
+    return DecisionAnswer(
+        classification=str(payload["classification"]),
+        purpose=str(payload["purpose"]),
+        shipped=bool(payload["shipped"]),
+        runtime_required=bool(payload["runtime_required"]),
+        lifecycle_owner=str(payload["lifecycle_owner"]),
+        executable=bool(payload["executable"]),
+    )
+
+
+def _workflow_status(record: DecisionRecord) -> str:
+    if record.status == "PENDING":
+        return "DECISION_REQUIRED"
+    if record.status == "RESOLVED" and record.application_status not in {"APPLIED", "LOCAL_APPLIED"}:
+        return "RESOLVED_APPLICATION_REQUIRED"
+    return record.status
+
+
+class DecisionService:
+    def __init__(self, store: DecisionStore, github: GitHubAppClient):
+        self.store = store
+        self.github = github
+
+    def _installation_for(self, repository: str) -> int:
+        installation = self.store.installation_for(repository)
+        if installation is not None:
+            return installation
+        installation = self.github.repository_installation(repository)
+        self.store.set_installation(repository, installation)
+        return installation
+
+    def gate(self, payload: dict[str, Any]) -> dict[str, object]:
+        for key in ("id", "repository", "branch", "subject_revision", "component_id", "request", "issue"):
+            if key not in payload:
+                raise ValueError(f"gate payload missing {key}")
+        record, stale = self.store.gate(payload)
+        installation = self._installation_for(record.repository)
+        for old in stale:
+            if old.issue_number:
+                try:
+                    self.github.add_issue_comment(
+                        old.repository,
+                        installation,
+                        old.issue_number,
+                        "PTSIP marked this clarification as stale because a newer component decision request replaced it.",
+                    )
+                    self.github.update_issue_state(old.repository, installation, old.issue_number, "closed")
+                except GitHubAPIError:
+                    pass
+        if record.status == "PENDING" and record.issue_number is None:
+            issue = payload["issue"]
+            if not isinstance(issue, dict):
+                raise ValueError("issue must be an object")
+            created = self.github.create_issue(
+                record.repository,
+                installation,
+                str(issue.get("title", f"[PTSIP clarification] {record.component_id}")),
+                str(issue.get("body", "")),
+            )
+            record = self.store.attach_issue(record.id, created.number, created.url)
+        elif record.status == "PENDING" and record.issue_number is not None:
+            # Issue open/closed state is only a UI surface. A manual close must
+            # not resolve the authoritative PENDING decision. Reopen it only
+            # when an active coding-agent gate actually needs the decision.
+            try:
+                self.github.update_issue_state(record.repository, installation, record.issue_number, "open")
+            except GitHubAPIError:
+                pass
+        return {"status": _workflow_status(record), "decision": record.as_dict()}
+
+    def decision(self, payload: dict[str, Any]) -> dict[str, object]:
+        decision_id = str(payload.get("decision_id", ""))
+        if not decision_id:
+            raise ValueError("decision_id is required")
+        record = self.store.get(decision_id)
+        if record is None:
+            raise KeyError(decision_id)
+        return {"status": _workflow_status(record), "decision": record.as_dict()}
+
+    def resolve_agent(self, payload: dict[str, Any]) -> dict[str, object]:
+        decision_id = str(payload.get("decision_id", ""))
+        raw_answer = payload.get("answer")
+        if not decision_id or not isinstance(raw_answer, dict):
+            raise ValueError("decision_id and answer are required")
+        answer = _answer_from_mapping(raw_answer)
+        validation = validate_answer(answer)
+        if not validation.valid:
+            return {"status": "CONFLICT", "validation": validation.as_dict()}
+        actor = str(payload.get("actor") or "coding-agent-session")
+        record, accepted = self.store.resolve(decision_id, answer.as_dict(), "AGENT_CHAT", actor)
+        return {
+            "status": "RESOLVED" if accepted else "ALREADY_RESOLVED",
+            "accepted": accepted,
+            "decision": record.as_dict(),
+            "validation": validation.as_dict(),
+        }
+
+    def application(self, payload: dict[str, Any]) -> dict[str, object]:
+        decision_id = str(payload.get("decision_id", ""))
+        status = str(payload.get("status", ""))
+        if status not in {"LOCAL_APPLIED", "FAILED", "STALE"}:
+            raise ValueError("unsupported agent application status")
+        existing = self.store.get(decision_id)
+        if existing is None:
+            raise KeyError(decision_id)
+        if existing.status != "RESOLVED":
+            raise ValueError("application state can be changed only for a resolved decision")
+        record = self.store.mark_application(
+            decision_id,
+            status,
+            str(payload.get("applied_revision") or "") or None,
+        )
+        if status == "LOCAL_APPLIED" and record.issue_number:
+            try:
+                installation = self._installation_for(record.repository)
+                self.github.add_issue_comment(
+                    record.repository,
+                    installation,
+                    record.issue_number,
+                    f"PTSIP decision `{record.id}` was resolved via `{record.resolution_source}` and applied by the active coding-agent workflow. Late replies are ignored.",
+                )
+                self.github.update_issue_state(record.repository, installation, record.issue_number, "closed")
+            except GitHubAPIError:
+                pass
+        return {"status": status, "decision": record.as_dict()}
+
+    def register_installation_event(self, payload: dict[str, Any]) -> None:
+        installation = payload.get("installation")
+        if not isinstance(installation, dict) or not isinstance(installation.get("id"), int):
+            return
+        installation_id = int(installation["id"])
+        repository = payload.get("repository")
+        if isinstance(repository, dict) and repository.get("full_name"):
+            self.store.set_installation(str(repository["full_name"]), installation_id)
+        for key in ("repositories", "repositories_added"):
+            repos = payload.get(key)
+            if isinstance(repos, list):
+                for item in repos:
+                    if isinstance(item, dict) and item.get("full_name"):
+                        self.store.set_installation(str(item["full_name"]), installation_id)
+
+    def issue_comment(self, payload: dict[str, Any]) -> dict[str, object]:
+        if payload.get("action") != "created":
+            return {"status": "IGNORED"}
+        self.register_installation_event(payload)
+        repository = payload.get("repository")
+        issue = payload.get("issue")
+        comment = payload.get("comment")
+        sender = payload.get("sender")
+        if not all(isinstance(item, dict) for item in (repository, issue, comment, sender)):
+            return {"status": "IGNORED"}
+        full_name = str(repository.get("full_name", ""))
+        issue_number = issue.get("number")
+        username = str(sender.get("login", ""))
+        body = str(comment.get("body", ""))
+        if not full_name or not isinstance(issue_number, int) or not username:
+            return {"status": "IGNORED"}
+        record = self.store.by_issue(full_name, issue_number)
+        if record is None:
+            return {"status": "IGNORED_NOT_PTSIP"}
+        if record.status != "PENDING":
+            return {"status": "IGNORED_TERMINAL_DECISION", "decision": record.as_dict()}
+        try:
+            installation = self._installation_for(full_name)
+        except GitHubAPIError:
+            return {"status": "IGNORED_NO_INSTALLATION"}
+        try:
+            permission = self.github.permission(full_name, installation, username)
+        except GitHubAPIError:
+            permission = "none"
+        if permission not in WRITE_PERMISSIONS:
+            return {"status": "IGNORED_UNAUTHORIZED"}
+        try:
+            answer = parse_answer(body)
+        except ValueError as exc:
+            return {"status": "IGNORED_UNSTRUCTURED", "error": str(exc)}
+        validation = validate_answer(answer)
+        if not validation.valid:
+            self.github.add_issue_comment(
+                full_name,
+                installation,
+                issue_number,
+                "PTSIP could not accept this decision because it conflicts with the fixed resolution rules:\n\n- "
+                + "\n- ".join(validation.errors),
+            )
+            return {"status": "CONFLICT", "validation": validation.as_dict()}
+
+        # Validate the answer against the profile at the exact gate snapshot
+        # before it is allowed to win the authoritative compare-and-set.
+        try:
+            projected_content = self._prepare_remote_projection(record, installation, answer)
+        except ValueError as exc:
+            self.github.add_issue_comment(
+                full_name,
+                installation,
+                issue_number,
+                "PTSIP could not accept this decision because it conflicts with the declared/projected profile:\n\n- "
+                + str(exc),
+            )
+            return {"status": "CONFLICT", "error": str(exc)}
+
+        resolved, accepted = self.store.resolve(record.id, answer.as_dict(), "GITHUB_ISSUE", username)
+        if not accepted:
+            return {"status": "IGNORED_TERMINAL_DECISION", "decision": resolved.as_dict()}
+        try:
+            self._apply_remote(resolved, installation, projected_content)
+        except Exception as exc:
+            self.store.mark_application(record.id, "FAILED")
+            try:
+                self.github.add_issue_comment(
+                    record.repository,
+                    installation,
+                    issue_number,
+                    "PTSIP accepted this decision but could not apply the profile automatically. "
+                    f"A coding agent must reconcile the already resolved decision: `{exc}`",
+                )
+                self.github.update_issue_state(record.repository, installation, issue_number, "closed")
+            except GitHubAPIError:
+                pass
+        final = self.store.get(record.id)
+        assert final is not None
+        return {"status": "RESOLVED", "decision": final.as_dict()}
+
+    def _prepare_remote_projection(
+        self,
+        record: DecisionRecord,
+        installation: int,
+        answer: DecisionAnswer,
+    ) -> str:
+        existing_text = self.github.file_text(record.repository, installation, "ptsip.yaml", record.subject_revision)
+        existing = load_profile_text(existing_text)
+        include = record.request.get("include", [])
+        if not isinstance(include, list):
+            raise ValueError("decision request include must be a list")
+        projected = project_payload(existing, record.component_id, [str(item) for item in include], answer)
+        projected_errors = validate_projected_payload(projected)
+        if projected_errors:
+            raise ValueError("Projected PTSIP profile is invalid: " + "; ".join(projected_errors))
+        return dump_payload(projected)
+
+    def _apply_remote(self, record: DecisionRecord, installation: int, projected_content: str) -> None:
+        current = self.github.branch_head(record.repository, installation, record.branch)
+        if current != record.subject_revision:
+            self.store.mark_application(record.id, "STALE")
+            if record.issue_number:
+                self.github.add_issue_comment(
+                    record.repository,
+                    installation,
+                    record.issue_number,
+                    "The decision was accepted, but the target branch changed after the last active decision gate. "
+                    "PTSIP did not modify the profile. A coding agent must re-run the gate against the current revision and can reconcile the already authoritative answer without asking the user to decide again.",
+                )
+                self.github.update_issue_state(record.repository, installation, record.issue_number, "closed")
+            return
+        commit_sha = self.github.commit_file_at_parent(
+            record.repository,
+            installation,
+            record.branch,
+            record.subject_revision,
+            "ptsip.yaml",
+            projected_content,
+            f"ptsip: apply decision {record.id}",
+        )
+        self.store.mark_application(record.id, "APPLIED", commit_sha)
+        if record.issue_number:
+            self.github.add_issue_comment(
+                record.repository,
+                installation,
+                record.issue_number,
+                f"PTSIP applied decision `{record.id}` in commit `{commit_sha}`. Late replies are ignored.",
+            )
+            self.github.update_issue_state(record.repository, installation, record.issue_number, "closed")

ptsip/app/store.py

@@ -0,0 +1,233 @@
+from __future__ import annotations
+
+import json
+import sqlite3
+import threading
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+
+@dataclass(frozen=True)
+class DecisionRecord:
+    id: str
+    repository: str
+    branch: str
+    subject_revision: str
+    component_id: str
+    request: dict[str, object]
+    status: str
+    answer: dict[str, object] | None
+    resolution_source: str | None
+    resolved_by: str | None
+    application_status: str
+    applied_revision: str | None
+    issue_number: int | None
+    issue_url: str | None
+
+    def as_dict(self) -> dict[str, object]:
+        return {
+            "id": self.id,
+            "repository": self.repository,
+            "branch": self.branch,
+            "subject_revision": self.subject_revision,
+            "component_id": self.component_id,
+            "request": self.request,
+            "status": self.status,
+            "answer": self.answer,
+            "resolution_source": self.resolution_source,
+            "resolved_by": self.resolved_by,
+            "application_status": self.application_status,
+            "applied_revision": self.applied_revision,
+            "issue_number": self.issue_number,
+            "issue_url": self.issue_url,
+        }
+
+
+class DecisionStore:
+    def __init__(self, path: str | Path):
+        self.path = Path(path).expanduser().resolve()
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self._lock = threading.RLock()
+        self._init()
+
+    def _connect(self) -> sqlite3.Connection:
+        conn = sqlite3.connect(self.path, timeout=30)
+        conn.row_factory = sqlite3.Row
+        return conn
+
+    def _init(self) -> None:
+        with self._connect() as conn:
+            conn.executescript(
+                """
+                PRAGMA journal_mode=WAL;
+                CREATE TABLE IF NOT EXISTS installations (
+                    repository TEXT PRIMARY KEY,
+                    installation_id INTEGER NOT NULL
+                );
+                CREATE TABLE IF NOT EXISTS decisions (
+                    id TEXT PRIMARY KEY,
+                    repository TEXT NOT NULL,
+                    branch TEXT NOT NULL,
+                    subject_revision TEXT NOT NULL,
+                    component_id TEXT NOT NULL,
+                    request_json TEXT NOT NULL,
+                    status TEXT NOT NULL DEFAULT 'PENDING',
+                    answer_json TEXT,
+                    resolution_source TEXT,
+                    resolved_by TEXT,
+                    application_status TEXT NOT NULL DEFAULT 'NOT_APPLIED',
+                    applied_revision TEXT,
+                    issue_number INTEGER,
+                    issue_url TEXT,
+                    created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+                    updated_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
+                );
+                CREATE INDEX IF NOT EXISTS idx_decision_issue
+                    ON decisions(repository, issue_number);
+                CREATE INDEX IF NOT EXISTS idx_decision_component
+                    ON decisions(repository, component_id, status);
+                """
+            )
+
+    @staticmethod
+    def _record(row: sqlite3.Row) -> DecisionRecord:
+        return DecisionRecord(
+            id=str(row["id"]),
+            repository=str(row["repository"]),
+            branch=str(row["branch"]),
+            subject_revision=str(row["subject_revision"]),
+            component_id=str(row["component_id"]),
+            request=json.loads(str(row["request_json"])),
+            status=str(row["status"]),
+            answer=json.loads(str(row["answer_json"])) if row["answer_json"] else None,
+            resolution_source=str(row["resolution_source"]) if row["resolution_source"] else None,
+            resolved_by=str(row["resolved_by"]) if row["resolved_by"] else None,
+            application_status=str(row["application_status"]),
+            applied_revision=str(row["applied_revision"]) if row["applied_revision"] else None,
+            issue_number=int(row["issue_number"]) if row["issue_number"] is not None else None,
+            issue_url=str(row["issue_url"]) if row["issue_url"] else None,
+        )
+
+    def set_installation(self, repository: str, installation_id: int) -> None:
+        with self._lock, self._connect() as conn:
+            conn.execute(
+                "INSERT INTO installations(repository, installation_id) VALUES (?, ?) "
+                "ON CONFLICT(repository) DO UPDATE SET installation_id=excluded.installation_id",
+                (repository, installation_id),
+            )
+
+    def installation_for(self, repository: str) -> int | None:
+        with self._connect() as conn:
+            row = conn.execute(
+                "SELECT installation_id FROM installations WHERE repository=?", (repository,)
+            ).fetchone()
+        return int(row[0]) if row else None
+
+    def gate(self, payload: dict[str, Any]) -> tuple[DecisionRecord, tuple[DecisionRecord, ...]]:
+        decision_id = str(payload["id"])
+        repository = str(payload["repository"])
+        branch = str(payload["branch"])
+        revision = str(payload["subject_revision"])
+        component_id = str(payload["component_id"])
+        request = payload["request"]
+        if not isinstance(request, dict):
+            raise ValueError("request must be an object")
+        request_json = json.dumps(request, ensure_ascii=False)
+        stale: list[DecisionRecord] = []
+        with self._lock, self._connect() as conn:
+            conn.execute("BEGIN IMMEDIATE")
+            rows = conn.execute(
+                "SELECT * FROM decisions WHERE repository=? AND component_id=? AND status='PENDING' AND id<>?",
+                (repository, component_id, decision_id),
+            ).fetchall()
+            for row in rows:
+                stale.append(self._record(row))
+            conn.execute(
+                "UPDATE decisions SET status='STALE', updated_at=CURRENT_TIMESTAMP "
+                "WHERE repository=? AND component_id=? AND status='PENDING' AND id<>?",
+                (repository, component_id, decision_id),
+            )
+            conn.execute(
+                "INSERT OR IGNORE INTO decisions(id, repository, branch, subject_revision, component_id, request_json) "
+                "VALUES (?, ?, ?, ?, ?, ?)",
+                (decision_id, repository, branch, revision, component_id, request_json),
+            )
+            # A gate call is an active-agent observation, not a timer. When the
+            # same semantic decision (same ID/component/selectors) is still
+            # pending or needs application retry, rebind its target snapshot to
+            # the revision the agent is actually working on. The human answer,
+            # resolution source and first-winner identity are never changed.
+            conn.execute(
+                "UPDATE decisions SET branch=?, subject_revision=?, request_json=?, updated_at=CURRENT_TIMESTAMP "
+                "WHERE id=? AND (status='PENDING' OR (status='RESOLVED' AND application_status IN ('NOT_APPLIED','FAILED','STALE')))",
+                (branch, revision, request_json, decision_id),
+            )
+            row = conn.execute("SELECT * FROM decisions WHERE id=?", (decision_id,)).fetchone()
+            assert row is not None
+            conn.commit()
+        return self._record(row), tuple(stale)
+
+    def get(self, decision_id: str) -> DecisionRecord | None:
+        with self._connect() as conn:
+            row = conn.execute("SELECT * FROM decisions WHERE id=?", (decision_id,)).fetchone()
+        return self._record(row) if row else None
+
+    def by_issue(self, repository: str, issue_number: int) -> DecisionRecord | None:
+        with self._connect() as conn:
+            row = conn.execute(
+                "SELECT * FROM decisions WHERE repository=? AND issue_number=? ORDER BY created_at DESC LIMIT 1",
+                (repository, issue_number),
+            ).fetchone()
+        return self._record(row) if row else None
+
+    def attach_issue(self, decision_id: str, issue_number: int, issue_url: str) -> DecisionRecord:
+        with self._lock, self._connect() as conn:
+            conn.execute(
+                "UPDATE decisions SET issue_number=?, issue_url=?, updated_at=CURRENT_TIMESTAMP WHERE id=?",
+                (issue_number, issue_url, decision_id),
+            )
+        record = self.get(decision_id)
+        assert record is not None
+        return record
+
+    def resolve(
+        self,
+        decision_id: str,
+        answer: dict[str, object],
+        source: str,
+        actor: str,
+    ) -> tuple[DecisionRecord, bool]:
+        answer_json = json.dumps(answer, ensure_ascii=False)
+        with self._lock, self._connect() as conn:
+            conn.execute("BEGIN IMMEDIATE")
+            changed = conn.execute(
+                "UPDATE decisions SET status='RESOLVED', answer_json=?, resolution_source=?, resolved_by=?, "
+                "updated_at=CURRENT_TIMESTAMP WHERE id=? AND status='PENDING'",
+                (answer_json, source, actor, decision_id),
+            ).rowcount
+            row = conn.execute("SELECT * FROM decisions WHERE id=?", (decision_id,)).fetchone()
+            if row is None:
+                conn.rollback()
+                raise KeyError(decision_id)
+            retry_allowed = False
+            if not changed and source == "AGENT_CHAT":
+                existing_answer = json.loads(str(row["answer_json"])) if row["answer_json"] else None
+                retry_allowed = (
+                    str(row["status"]) == "RESOLVED"
+                    and str(row["application_status"]) in {"NOT_APPLIED", "FAILED", "STALE"}
+                    and existing_answer == answer
+                )
+            conn.commit()
+        return self._record(row), bool(changed or retry_allowed)
+
+    def mark_application(self, decision_id: str, status: str, applied_revision: str | None = None) -> DecisionRecord:
+        with self._lock, self._connect() as conn:
+            conn.execute(
+                "UPDATE decisions SET application_status=?, applied_revision=?, updated_at=CURRENT_TIMESTAMP WHERE id=?",
+                (status, applied_revision, decision_id),
+            )
+        record = self.get(decision_id)
+        if record is None:
+            raise KeyError(decision_id)
+        return record

ptsip/artifact_evidence.py

@@ -0,0 +1,150 @@
+from __future__ import annotations
+
+import json
+import hashlib
+from dataclasses import asdict, dataclass
+from importlib.resources import files
+from pathlib import Path
+
+import yaml
+from jsonschema import Draft202012Validator
+
+from .repository.discover import RepositoryInfo
+from .repository.snapshot import capture_snapshot
+
+
+@dataclass(frozen=True)
+class ArtifactEvidenceDocument:
+    source_path: str
+    source_sha256: str
+    binding_path: str | None
+    binding_valid: bool
+    payload: dict[str, object]
+
+    def as_dict(self) -> dict[str, object]:
+        return {
+            "source_path": self.source_path,
+            "source_sha256": self.source_sha256,
+            "binding_path": self.binding_path,
+            "binding_valid": self.binding_valid,
+            "payload": self.payload,
+        }
+
+
+@dataclass(frozen=True)
+class ArtifactEvidenceIssue:
+    source_path: str
+    message: str
+
+    def as_dict(self) -> dict[str, str]:
+        return asdict(self)
+
+
+@dataclass(frozen=True)
+class ArtifactEvidenceLoad:
+    documents: tuple[ArtifactEvidenceDocument, ...]
+    issues: tuple[ArtifactEvidenceIssue, ...]
+
+    def as_dict(self) -> dict[str, object]:
+        return {
+            "documents": [item.as_dict() for item in self.documents],
+            "issues": [item.as_dict() for item in self.issues],
+            "document_count": len(self.documents),
+            "valid": not self.issues,
+        }
+
+
+def _schema() -> dict[str, object]:
+    path = files("ptsip").joinpath("specdata/ptsip-artifact-evidence.schema.json")
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def _binding_issue(
+    artifact_path: Path,
+    digest: str,
+    repository: RepositoryInfo,
+) -> tuple[str | None, str | None]:
+    binding_path = Path(str(artifact_path) + ".binding.json")
+    if not binding_path.is_file():
+        return str(binding_path), "Artifact evidence has no revision-binding sidecar."
+    try:
+        binding = yaml.safe_load(binding_path.read_text(encoding="utf-8-sig"))
+    except (OSError, UnicodeError, yaml.YAMLError) as exc:
+        return str(binding_path), f"Unable to parse artifact evidence binding: {exc}"
+    if not isinstance(binding, dict) or binding.get("format") != "ptsip-artifact-evidence-binding/v1":
+        return str(binding_path), "Artifact evidence binding format must be 'ptsip-artifact-evidence-binding/v1'."
+    subject = binding.get("subject")
+    if not isinstance(subject, dict):
+        return str(binding_path), "Artifact evidence binding requires a subject object."
+    expected_repositories = {repository.root}
+    if repository.remote and repository.remote.repository:
+        expected_repositories.add(repository.remote.repository)
+    if subject.get("repository") not in expected_repositories:
+        return str(binding_path), "Artifact evidence binding repository does not match the evaluated Consumer Repository."
+    if not repository.commit or subject.get("revision") != repository.commit:
+        return str(binding_path), "Artifact evidence binding revision does not match the evaluated repository revision."
+    if binding.get("artifact_sha256") != digest:
+        return str(binding_path), "Artifact evidence binding SHA-256 does not match the imported document."
+    snapshot_fingerprint = capture_snapshot(repository.root).tracked_content_fingerprint
+    if subject.get("tracked_content_sha256") != snapshot_fingerprint:
+        return str(binding_path), "Artifact evidence binding tracked-content fingerprint does not match the evaluated repository snapshot."
+    return str(binding_path), None
+
+
+def load_artifact_evidence(
+    paths: list[str | Path] | tuple[str | Path, ...] | None,
+    repository: RepositoryInfo | None = None,
+) -> ArtifactEvidenceLoad:
+    if not paths:
+        return ArtifactEvidenceLoad((), ())
+
+    validator = Draft202012Validator(_schema())
+    documents: list[ArtifactEvidenceDocument] = []
+    issues: list[ArtifactEvidenceIssue] = []
+    seen_ids: dict[str, str] = {}
+
+    for raw_path in paths:
+        path = Path(raw_path).expanduser().resolve()
+        source = str(path)
+        if not path.is_file():
+            issues.append(ArtifactEvidenceIssue(source, "Artifact evidence file does not exist or is not a file."))
+            continue
+        try:
+            raw = path.read_bytes()
+            digest = hashlib.sha256(raw).hexdigest()
+            payload = yaml.safe_load(raw.decode("utf-8-sig"))
+        except (OSError, UnicodeError, yaml.YAMLError) as exc:
+            issues.append(ArtifactEvidenceIssue(source, f"Unable to parse artifact evidence: {exc}"))
+            continue
+        if not isinstance(payload, dict):
+            issues.append(ArtifactEvidenceIssue(source, "Artifact evidence root must be a mapping/object."))
+            continue
+
+        validation_errors = sorted(validator.iter_errors(payload), key=lambda item: list(item.absolute_path))
+        if validation_errors:
+            for error in validation_errors:
+                location = ".".join(str(item) for item in error.absolute_path) or "<root>"
+                issues.append(ArtifactEvidenceIssue(source, f"{location}: {error.message}"))
+            continue
+
+        artifact_id = str(payload["artifact_id"])
+        previous = seen_ids.get(artifact_id)
+        if previous is not None:
+            issues.append(
+                ArtifactEvidenceIssue(
+                    source,
+                    f"Duplicate artifact_id {artifact_id!r}; already supplied by {previous}.",
+                )
+            )
+            continue
+        seen_ids[artifact_id] = source
+        binding_path: str | None = None
+        binding_valid = repository is None
+        if repository is not None:
+            binding_path, binding_error = _binding_issue(path, digest, repository)
+            binding_valid = binding_error is None
+            if binding_error is not None:
+                issues.append(ArtifactEvidenceIssue(binding_path or source, binding_error))
+        documents.append(ArtifactEvidenceDocument(source, digest, binding_path, binding_valid, payload))
+
+    return ArtifactEvidenceLoad(tuple(documents), tuple(issues))