backloop-sdk 0.1.0__py3-none-any.whl

backloop/redact.py

@@ -0,0 +1,108 @@
+"""
+Best-effort removal of secrets and personal data from feedback before it
+leaves the agent. The protocol forbids sending them; this catches mistakes.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Iterable, Optional, TypeVar, Union
+
+T = TypeVar("T")
+
+REDACTED = "[REDACTED]"
+
+# Patterns use re.ASCII so \b and \d behave like the (non-unicode) JS regexes
+# in redact.ts. JS's \s is Unicode-aware, so it is spelled out where it matters.
+_A = re.ASCII
+_WS = r"\s   - 

  　"
+
+_SECRET_PATTERNS = [
+    re.compile(r"-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----", _A),
+    re.compile(rf"\bBearer[{_WS}]+[A-Za-z0-9\-._~+/]{{8,}}=*", _A | re.I),
+    re.compile(rf"\bBasic[{_WS}]+[A-Za-z0-9+/]{{8,}}=*", _A),
+    re.compile(r"\beyJ[A-Za-z0-9_-]{5,}\.[A-Za-z0-9_-]{5,}\.[A-Za-z0-9_-]{5,}\b", _A),  # JWT
+    re.compile(r"\bsk-(?:ant-|proj-)?[A-Za-z0-9_-]{16,}\b", _A),  # Anthropic / OpenAI style
+    re.compile(r"\b(?:sk|pk|rk)_(?:live|test)_[A-Za-z0-9]{10,}\b", _A),  # Stripe
+    re.compile(r"\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{20,}\b", _A),  # GitHub
+    re.compile(r"\bgithub_pat_[A-Za-z0-9_]{20,}\b", _A),
+    re.compile(r"\bxox[abprs]-[A-Za-z0-9-]{10,}\b", _A),  # Slack
+    re.compile(r"\bAKIA[0-9A-Z]{16}\b", _A),  # AWS access key id
+    re.compile(r"\bAIza[0-9A-Za-z_-]{35}\b", _A),  # Google API key
+    re.compile(
+        rf"([?&](?:api_?key|access_token|token|secret|password|signature)=)[^&{_WS}\"']+",
+        _A | re.I,
+    ),
+]
+
+_EMAIL = re.compile(r"\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b", _A)
+_CARD_CANDIDATE = re.compile(r"\b(?:\d[ -]?){12,18}\d\b", _A)
+
+_SENSITIVE_KEY = re.compile(
+    r"authorization|cookie|set-cookie|password|passwd|secret|client_secret|api[_-]?key|x-api-key"
+    r"|access[_-]?token|refresh[_-]?token|token|private[_-]?key|ssn|card[_-]?number|cvv",
+    _A | re.I,
+)
+
+PatternLike = Union[str, "re.Pattern[str]"]
+
+
+def _luhn(digits: str) -> bool:
+    total = 0
+    double = False
+    for ch in reversed(digits):
+        d = ord(ch) - 48
+        if double:
+            d *= 2
+            if d > 9:
+                d -= 9
+        total += d
+        double = not double
+    return total % 10 == 0
+
+
+def _replace_secret(match: re.Match[str]) -> str:
+    # Keep a leading capture group (e.g. "?api_key=") and redact the rest.
+    prefix = match.group(1) if match.re.groups else None
+    if isinstance(prefix, str) and match.group(0).startswith(prefix):
+        return prefix + REDACTED
+    return REDACTED
+
+
+def _replace_card(match: re.Match[str]) -> str:
+    digits = re.sub(r"[ -]", "", match.group(0))
+    return REDACTED if 13 <= len(digits) <= 19 and _luhn(digits) else match.group(0)
+
+
+def redact_string(
+    value: str, emails: bool = True, patterns: Optional[Iterable[PatternLike]] = None
+) -> str:
+    """Redact secrets, card numbers and (unless ``emails=False``) email addresses in a string."""
+    out = value
+    extra = [re.compile(p) if isinstance(p, str) else p for p in (patterns or ())]
+    for pattern in [*_SECRET_PATTERNS, *extra]:
+        out = pattern.sub(_replace_secret, out)
+    out = _CARD_CANDIDATE.sub(_replace_card, out)
+    if emails:
+        out = _EMAIL.sub(REDACTED, out)
+    return out
+
+
+def redact(value: T, emails: bool = True, patterns: Optional[Iterable[PatternLike]] = None) -> T:
+    """Recursively redact every string in a JSON value, and the values of sensitive keys.
+
+    Returns a new value; the input is not modified.
+    """
+    extra = list(patterns or ())
+    if isinstance(value, str):
+        return redact_string(value, emails, extra)  # type: ignore[return-value]
+    if isinstance(value, (list, tuple)):
+        return [redact(v, emails, extra) for v in value]  # type: ignore[return-value]
+    if isinstance(value, dict):
+        return {  # type: ignore[return-value]
+            key: REDACTED
+            if isinstance(key, str) and _SENSITIVE_KEY.fullmatch(key) and v is not None
+            else redact(v, emails, extra)
+            for key, v in value.items()
+        }
+    return value

backloop/server.py

@@ -0,0 +1,206 @@
+"""Framework-agnostic handler for ``POST /feedback`` and the discovery document."""
+
+from __future__ import annotations
+
+import inspect
+import json
+import logging
+import math
+import re
+import threading
+from datetime import datetime, timezone
+from typing import Any, Callable, Dict, List, Mapping, Optional, Tuple, Union
+
+from .ids import new_id
+from .types import (
+    DEFAULT_MAX_BYTES,
+    FEEDBACK_TYPES,
+    LINK_REL,
+    SPEC_VERSION,
+    AuthMode,
+    DiscoveryDocument,
+    FeedbackRecord,
+    FeedbackSource,
+    ValidationIssue,
+)
+from .validate import format_issues, validate_submission
+
+logger = logging.getLogger("backloop")
+
+#: ``(status, json_body, headers)``, ready to hand to any web framework.
+HandlerResponse = Tuple[int, Dict[str, Any], Dict[str, str]]
+#: What ``on_record`` may return: ``{"known_issue": {...}}`` to pass back to the agent, or None.
+OnRecordResult = Optional[Mapping[str, Any]]
+OnRecord = Callable[[FeedbackRecord], OnRecordResult]
+
+JSON_HEADERS = {"content-type": "application/json; charset=utf-8"}
+_JSON_CONTENT_TYPE = re.compile(r"application/(?:[\w.+-]+\+)?json\b", re.I | re.ASCII)
+
+
+def error_response(
+    status: int,
+    code: str,
+    message: str,
+    details: Optional[List[ValidationIssue]] = None,
+    headers: Optional[Dict[str, str]] = None,
+) -> HandlerResponse:
+    """Build a protocol error: ``{"error": {"code", "message", "details"?}}``."""
+    error: Dict[str, Any] = {"code": code, "message": message}
+    if details is not None:
+        error["details"] = details
+    return status, {"error": error}, {**JSON_HEADERS, **(headers or {})}
+
+
+def feedback_link_header(path: str = "/feedback") -> str:
+    """``Link`` header value advertising the feedback endpoint. Add it to your API's error responses."""
+    return f'<{path}>; rel="{LINK_REL}"'
+
+
+class _RateLimiter:
+    def __init__(self, limit: int, window: float) -> None:
+        self._limit = limit
+        self._window = window
+        self._hits: Dict[str, List[float]] = {}  # key -> [count, reset_at]
+        self._lock = threading.Lock()
+
+    def take(self, key: str, now: float) -> int:
+        """Returns seconds to wait, or 0 if allowed."""
+        with self._lock:
+            entry = self._hits.get(key)
+            if entry is None or entry[1] <= now:
+                if len(self._hits) > 10_000:
+                    self._hits.clear()
+                self._hits[key] = [1, now + self._window]
+                return 0
+            entry[0] += 1
+            return math.ceil(entry[1] - now) if entry[0] > self._limit else 0
+
+
+def _reject_constant(name: str) -> Any:
+    raise ValueError(f"{name} is not valid JSON")
+
+
+class FeedbackHandler:
+    """Validates submissions, builds records and hands them to ``on_record``.
+
+    Framework-agnostic: your route reads the body and the caller's account,
+    calls ``handle_submit`` and returns the ``(status, body, headers)`` it gets.
+
+    - ``on_record(record)`` stores or forwards each accepted record. It may
+      return ``{"known_issue": {...}}`` to pass back to the agent. If it raises,
+      the agent gets ``503 unavailable``.
+    - ``identify(request)`` resolves the (pseudonymous, see ``hash_account``)
+      account behind a framework request; used by the integrations.
+    - ``rate_limit`` is ``(max, window_seconds)`` per account (or per IP), or
+      None to disable it.
+    """
+
+    def __init__(
+        self,
+        on_record: OnRecord,
+        *,
+        service: Optional[str] = None,
+        identify: Optional[Callable[[Any], Any]] = None,
+        auth: AuthMode = "optional",
+        max_bytes: int = DEFAULT_MAX_BYTES,
+        public_endpoint: Optional[str] = None,
+        rate_limit: Optional[Tuple[int, float]] = (60, 60.0),
+        source: FeedbackSource = "http",
+        generate_id: Optional[Callable[[], str]] = None,
+        now: Optional[Callable[[], datetime]] = None,
+    ) -> None:
+        if inspect.iscoroutinefunction(on_record):
+            raise TypeError("on_record must be a regular (synchronous) function")
+        self.on_record = on_record
+        self.service = service
+        self.identify = identify
+        self.auth = auth
+        self.max_bytes = max_bytes
+        self.public_endpoint = public_endpoint
+        self.source = source
+        self._limiter = _RateLimiter(*rate_limit) if rate_limit else None
+        self._generate_id = generate_id or (lambda: new_id("fb"))
+        self._now = now or (lambda: datetime.now(timezone.utc))
+
+    def handle_submit(
+        self,
+        body: Union[bytes, str],
+        content_type: Optional[str],
+        account: Optional[str] = None,
+        client_ip: Optional[str] = None,
+    ) -> HandlerResponse:
+        """Handle ``POST /feedback``. Returns ``(status, json_body, headers)``."""
+        raw = body.encode("utf-8") if isinstance(body, str) else bytes(body)
+        if not _JSON_CONTENT_TYPE.match(content_type or ""):
+            return error_response(415, "unsupported_media_type", "Content-Type must be application/json")
+        if len(raw) > self.max_bytes:
+            return error_response(413, "payload_too_large", f"Feedback is limited to {self.max_bytes} bytes")
+        if self.auth == "required" and not account:
+            return error_response(
+                401, "unauthorized", "Authenticate with the same credentials as the rest of the API"
+            )
+
+        if self._limiter is not None:
+            key = account if account is not None else client_ip if client_ip is not None else "anonymous"
+            wait = self._limiter.take(key, self._utc_now().timestamp())
+            if wait > 0:
+                return error_response(
+                    429, "rate_limited", "Too many feedback submissions", headers={"retry-after": str(wait)}
+                )
+
+        try:
+            # Decode like fetch's Request.text(): UTF-8, BOM stripped, invalid bytes replaced.
+            parsed = json.loads(raw.decode("utf-8-sig", "replace"), parse_constant=_reject_constant)
+        except ValueError:
+            return error_response(400, "invalid_json", "Body is not valid JSON")
+        result = validate_submission(parsed)
+        if not result.valid:
+            return error_response(400, "invalid_feedback", format_issues(result.issues), result.issues)
+
+        record: FeedbackRecord = {"id": self._generate_id(), "received_at": _iso(self._utc_now())}  # type: ignore[typeddict-item]
+        if self.service:
+            record["service"] = self.service
+        if account:
+            record["account"] = account
+        record["source"] = self.source or "http"
+        record["feedback"] = parsed
+
+        try:
+            outcome = self.on_record(record)
+        except Exception:
+            logger.exception("[backloop] failed to store feedback record")
+            return error_response(
+                503, "unavailable", "Feedback could not be stored. Retry once later.", headers={"retry-after": "5"}
+            )
+
+        ack: Dict[str, Any] = {"id": record["id"], "status": "accepted", "received_at": record["received_at"]}
+        known_issue = outcome.get("known_issue") if isinstance(outcome, Mapping) else None
+        if known_issue:
+            ack["known_issue"] = known_issue
+        return 202, ack, dict(JSON_HEADERS)
+
+    def discovery(self, base_url: Optional[str] = None) -> DiscoveryDocument:
+        """The document for ``GET /.well-known/agent-feedback``.
+
+        The endpoint is ``public_endpoint`` if set, else ``{base_url}/feedback``.
+        """
+        endpoint = self.public_endpoint
+        if endpoint is None:
+            endpoint = (base_url or "").rstrip("/") + "/feedback"
+        return {
+            "spec_version": SPEC_VERSION,
+            "endpoint": endpoint,
+            "types": list(FEEDBACK_TYPES),  # type: ignore[typeddict-item]
+            "max_bytes": self.max_bytes,
+            "auth": self.auth,
+        }
+
+    def _utc_now(self) -> datetime:
+        now = self._now()
+        return now.replace(tzinfo=timezone.utc) if now.tzinfo is None else now
+
+
+def _iso(dt: datetime) -> str:
+    """Format like ``Date.toISOString()``: UTC, millisecond precision."""
+    dt = dt.astimezone(timezone.utc)
+    return dt.strftime("%Y-%m-%dT%H:%M:%S.") + f"{dt.microsecond // 1000:03d}Z"

backloop/tool.py

@@ -0,0 +1,40 @@
+"""The ``submit_feedback`` tool for LLM tool-calling APIs (spec §7)."""
+
+from __future__ import annotations
+
+import copy
+from typing import Any, Dict, Optional
+
+from ._generated import FEEDBACK_SCHEMA, FEEDBACK_TOOL_DESCRIPTION
+
+FEEDBACK_TOOL_NAME = "submit_feedback"
+
+
+def feedback_tool_input_schema() -> Dict[str, Any]:
+    """
+    JSON Schema for the tool's input: the submission schema without
+    ``spec_version`` and without JSON-Schema meta keys, ready for any LLM
+    tool-calling API.
+    """
+    schema = copy.deepcopy(FEEDBACK_SCHEMA)
+    properties = schema["properties"]
+    properties.pop("spec_version", None)
+    return {
+        "type": "object",
+        "properties": properties,
+        "required": schema["required"],
+        "additionalProperties": schema["additionalProperties"],
+    }
+
+
+def feedback_tool(name: Optional[str] = None, description: Optional[str] = None) -> Dict[str, Any]:
+    """
+    The feedback tool in the shape the Claude Messages API expects
+    (``{"name", "description", "input_schema"}``). Add it to your agent's tools
+    and send its input with ``FeedbackClient.submit``.
+    """
+    return {
+        "name": name if name is not None else FEEDBACK_TOOL_NAME,
+        "description": description if description is not None else FEEDBACK_TOOL_DESCRIPTION,
+        "input_schema": feedback_tool_input_schema(),
+    }

backloop/types.py

@@ -0,0 +1,165 @@
+"""Protocol types and constants. See spec/*.schema.json."""
+
+from typing import Any, Dict, List, Literal, Tuple, TypedDict
+
+SPEC_VERSION = "0.1"
+
+FEEDBACK_TYPES: Tuple[str, ...] = (
+    "missing_capability",
+    "bug",
+    "unclear_documentation",
+    "unexpected_response",
+    "unhelpful_error",
+    "performance",
+    "other",
+)
+OUTCOMES: Tuple[str, ...] = ("blocked", "degraded", "completed")
+
+DEFAULT_MAX_BYTES = 16_384
+WELL_KNOWN_PATH = "/.well-known/agent-feedback"
+LINK_REL = "agent-feedback"
+
+FeedbackType = Literal[
+    "missing_capability",
+    "bug",
+    "unclear_documentation",
+    "unexpected_response",
+    "unhelpful_error",
+    "performance",
+    "other",
+]
+Outcome = Literal["blocked", "degraded", "completed"]
+HttpMethod = Literal["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"]
+FeedbackSource = Literal["http", "mcp", "sdk", "other"]
+KnownIssueStatus = Literal["acknowledged", "planned", "in_progress", "fixed", "wont_fix"]
+AuthMode = Literal["none", "optional", "required"]
+FeedbackErrorCode = Literal[
+    "invalid_json",
+    "invalid_feedback",
+    "unauthorized",
+    "payload_too_large",
+    "unsupported_media_type",
+    "rate_limited",
+    "method_not_allowed",
+    "unavailable",
+]
+
+
+class AgentInfo(TypedDict, total=False):
+    name: str
+    version: str
+    model: str
+    framework: str
+
+
+class Evidence(TypedDict, total=False):
+    status_code: int
+    request: Dict[str, Any]
+    response_excerpt: str
+
+
+class _FeedbackSubmissionRequired(TypedDict):
+    type: FeedbackType
+    goal: str
+    message: str
+
+
+class FeedbackSubmission(_FeedbackSubmissionRequired, total=False):
+    """What an agent sends to ``POST /feedback``. See spec/feedback.schema.json."""
+
+    spec_version: Literal["0.1"]
+    endpoint: str
+    method: HttpMethod
+    outcome: Outcome
+    workaround: bool
+    workaround_description: str
+    expected: str
+    suggestion: str
+    request_id: str
+    session_id: str
+    agent: AgentInfo
+    evidence: Evidence
+    metadata: Dict[str, Any]
+
+
+class _FeedbackRecordRequired(TypedDict):
+    id: str
+    received_at: str
+    feedback: FeedbackSubmission
+
+
+class FeedbackRecord(_FeedbackRecordRequired, total=False):
+    """A submission after a service accepted it. See spec/record.schema.json."""
+
+    service: str
+    account: str
+    source: FeedbackSource
+
+
+class _KnownIssueRequired(TypedDict):
+    id: str
+    title: str
+    status: KnownIssueStatus
+
+
+class KnownIssue(_KnownIssueRequired, total=False):
+    url: str
+    workaround: str
+
+
+class _FeedbackAckRequired(TypedDict):
+    id: str
+    status: Literal["accepted"]
+    received_at: str
+
+
+class FeedbackAck(_FeedbackAckRequired, total=False):
+    """Body of a ``202`` response. See spec/ack.schema.json."""
+
+    known_issue: KnownIssue
+
+
+class ValidationIssue(TypedDict):
+    """``path`` is a dot path to the offending field; ``""`` for the root object."""
+
+    path: str
+    message: str
+
+
+class _ErrorInfoRequired(TypedDict):
+    code: str
+    message: str
+
+
+class ErrorInfo(_ErrorInfoRequired, total=False):
+    details: List[ValidationIssue]
+
+
+class ErrorBody(TypedDict):
+    error: ErrorInfo
+
+
+class DiscoveryDocument(TypedDict):
+    """Served at ``GET /.well-known/agent-feedback``."""
+
+    spec_version: Literal["0.1"]
+    endpoint: str
+    types: List[FeedbackType]
+    max_bytes: int
+    auth: AuthMode
+
+
+class _IngestResultRequired(TypedDict):
+    id: str
+    status: Literal["accepted", "duplicate", "rejected"]
+
+
+class IngestResult(_IngestResultRequired, total=False):
+    known_issue: KnownIssue
+    error: ErrorInfo
+
+
+class IngestResponse(TypedDict):
+    """Collector response to ``POST /v1/records``."""
+
+    results: List[IngestResult]

backloop/validate.py

@@ -0,0 +1,175 @@
+"""
+A small JSON Schema interpreter covering exactly the keywords the protocol
+schemas use, so the SDK validates against spec/*.schema.json with zero
+dependencies. Mirrors validate.ts in the TypeScript SDK.
+"""
+
+from __future__ import annotations
+
+import json
+import math
+import re
+from dataclasses import dataclass, field
+from typing import Any, Dict, Generic, List, Optional, TypeVar
+
+from ._generated import ACK_SCHEMA, FEEDBACK_SCHEMA, RECORD_SCHEMA
+from .types import FeedbackAck, FeedbackRecord, FeedbackSubmission, ValidationIssue
+
+T = TypeVar("T")
+Schema = Dict[str, Any]
+
+_REFS: Dict[str, Schema] = {"feedback.schema.json": FEEDBACK_SCHEMA}
+
+_RFC3339 = re.compile(
+    r"\d{4}-\d{2}-\d{2}[Tt]\d{2}:\d{2}:\d{2}(\.\d+)?([Zz]|[+-]\d{2}:\d{2})", re.ASCII
+)
+
+
+def _type_of(value: Any) -> str:
+    """The JSON type of a Python value, as ``typeof`` would report it in validate.ts."""
+    if value is None:
+        return "null"
+    if isinstance(value, bool):
+        return "boolean"
+    if isinstance(value, (int, float)):
+        return "number"
+    if isinstance(value, str):
+        return "string"
+    if isinstance(value, (list, tuple)):
+        return "array"
+    if isinstance(value, dict):
+        return "object"
+    return type(value).__name__
+
+
+def _is_integer(value: Any) -> bool:
+    # Like Number.isInteger: 400 and 400.0 are integers, 400.5 and True are not.
+    if isinstance(value, bool):
+        return False
+    if isinstance(value, int):
+        return True
+    return isinstance(value, float) and math.isfinite(value) and value.is_integer()
+
+
+def _same(a: Any, b: Any) -> bool:
+    """JSON equality: unlike ``==``, ``True`` never equals ``1``."""
+    if isinstance(a, bool) or isinstance(b, bool):
+        return type(a) is type(b) and a == b
+    return a == b
+
+
+def _num(n: Any) -> str:
+    return str(int(n)) if isinstance(n, float) and n.is_integer() else str(n)
+
+
+def _check(schema: Schema, value: Any, path: str, issues: List[ValidationIssue]) -> None:
+    ref = schema.get("$ref")
+    if ref:
+        target = _REFS.get(ref)
+        if target is None:
+            raise ValueError(f"Unresolvable $ref {ref}")
+        _check(target, value, path, issues)
+        return
+
+    actual = _type_of(value)
+    expected = schema.get("type")
+    if expected == "object" and actual != "object":
+        issues.append({"path": path, "message": "must be an object"})
+        return
+    if expected == "string" and actual != "string":
+        issues.append({"path": path, "message": "must be a string"})
+        return
+    if expected == "boolean" and actual != "boolean":
+        issues.append({"path": path, "message": "must be a boolean"})
+        return
+    if expected == "integer" and not _is_integer(value):
+        issues.append({"path": path, "message": "must be an integer"})
+        return
+    if expected == "number" and not (actual == "number" and math.isfinite(value)):
+        issues.append({"path": path, "message": "must be a number"})
+        return
+
+    if "const" in schema and not _same(value, schema["const"]):
+        const = json.dumps(schema["const"], ensure_ascii=False)
+        issues.append({"path": path, "message": f"must be {const}"})
+    enum = schema.get("enum")
+    if enum is not None and not any(_same(value, option) for option in enum):
+        issues.append({"path": path, "message": "must be one of: " + ", ".join(map(str, enum))})
+
+    if actual == "string":
+        length = len(value)  # code points, as JSON Schema specifies
+        min_length = schema.get("minLength")
+        if min_length is not None and length < min_length:
+            message = (
+                "must not be empty" if min_length == 1 else f"must be at least {min_length} characters"
+            )
+            issues.append({"path": path, "message": message})
+        max_length = schema.get("maxLength")
+        if max_length is not None and length > max_length:
+            issues.append({"path": path, "message": f"must be at most {max_length} characters"})
+        if schema.get("format") == "date-time" and not _RFC3339.fullmatch(value):
+            issues.append({"path": path, "message": "must be an RFC 3339 date-time"})
+
+    if actual == "number":
+        minimum = schema.get("minimum")
+        if minimum is not None and value < minimum:
+            issues.append({"path": path, "message": f"must be >= {_num(minimum)}"})
+        maximum = schema.get("maximum")
+        if maximum is not None and value > maximum:
+            issues.append({"path": path, "message": f"must be <= {_num(maximum)}"})
+
+    if actual == "object" and ("properties" in schema or "required" in schema):
+        properties: Schema = schema.get("properties") or {}
+
+        def join(key: Any) -> str:
+            return f"{path}.{key}" if path else str(key)
+
+        for key in schema.get("required", ()):
+            if key not in value:
+                issues.append({"path": join(key), "message": "is required"})
+        for key, child in value.items():
+            child_schema = properties.get(key)
+            if child_schema is not None:
+                _check(child_schema, child, join(key), issues)
+            elif schema.get("additionalProperties") is False:
+                issues.append({"path": join(key), "message": "is not a recognised field"})
+
+
+@dataclass
+class ValidationResult(Generic[T]):
+    """``valid`` is True when ``issues`` is empty; ``value`` is then the validated input."""
+
+    valid: bool
+    issues: List[ValidationIssue] = field(default_factory=list)
+    value: Optional[T] = None
+
+    def __bool__(self) -> bool:
+        return self.valid
+
+
+def _run(schema: Schema, value: Any) -> ValidationResult[Any]:
+    issues: List[ValidationIssue] = []
+    _check(schema, value, "", issues)
+    if issues:
+        return ValidationResult(valid=False, issues=issues)
+    return ValidationResult(valid=True, issues=[], value=value)
+
+
+def validate_submission(value: Any) -> ValidationResult[FeedbackSubmission]:
+    """Validate an agent's submission against spec/feedback.schema.json."""
+    return _run(FEEDBACK_SCHEMA, value)
+
+
+def validate_record(value: Any) -> ValidationResult[FeedbackRecord]:
+    """Validate a stored/forwarded record against spec/record.schema.json."""
+    return _run(RECORD_SCHEMA, value)
+
+
+def validate_ack(value: Any) -> ValidationResult[FeedbackAck]:
+    """Validate a ``202`` acknowledgement against spec/ack.schema.json."""
+    return _run(ACK_SCHEMA, value)
+
+
+def format_issues(issues: List[ValidationIssue]) -> str:
+    """``"goal: must not be empty; type: is required"``."""
+    return "; ".join(f"{i['path']}: {i['message']}" if i["path"] else i["message"] for i in issues)