jev-mcp-python 0.1.0__py3-none-any.whl

jev_mcp/tools/extract.py

@@ -0,0 +1,262 @@
+"""jev_extract: regex finds candidates, Jev picks one, the value is returned verbatim (`index.ts:884-1128`).
+
+Hard invariants: a value is one of its field's candidates or null; a call with no candidates at all
+makes no provider request (and so never resolves the provider); an incomplete candidate universe
+(capped, or matches skipped as too long) is never `auto` and never a definite `not_found`.
+"""
+
+from dataclasses import dataclass
+from typing import Any
+
+from jev_mcp.domain import ChoiceQuestion, Question
+from jev_mcp.extract.candidates import Refused, find_candidates
+from jev_mcp.extract.dialect import to_units
+from jev_mcp.limits import EXTRACT
+from jev_mcp.policy import DEFAULT_CLASSIFY_AUTO_ACCEPT, DEFAULT_MINIMUM_MARGIN, ExtractFieldEvidence, ExtractJudgment
+from jev_mcp.serialize import quote
+from jev_mcp.text import length
+from jev_mcp.tools.base import JevTool, Runtime, ToolError, ToolResult, caller_actions, define, frame, headline
+from jev_mcp.tools.observed import decide_extract_field, validate_extract_choice
+from jev_mcp.validation import margin, top_probability
+from jev_mcp.validation.caps import CapLedger, candidate_budget_error, exceeds
+
+NONE_OF_THEM = "none_of_them"
+
+DEFINITION = define(
+    "jev_extract",
+    "Extract fields by regex, Jev picks the right match",
+    "Extract structured fields from a document with TypeSafe Jev as the picker, not the generator: your regex finds "
+    "candidate substrings in code, Jev chooses which candidate is the field's true value, and the result is "
+    "returned verbatim — never model-generated text. Fields with zero regex matches never reach the model "
+    "(not_found); if no field has matches, no API call is made. Ambiguous picks are flagged for review. Use for "
+    "prices, dates, version numbers, IDs, and anything with a recognizable shape; keep documents bounded.",
+    {
+        "type": "object",
+        "properties": {
+            "document": {
+                "type": "string",
+                "minLength": EXTRACT.document_min,
+                "maxLength": EXTRACT.document_max,
+                "description": f"The document to extract from. Rejected above {EXTRACT.document_max:,} characters.",
+            },
+            "fields": {
+                "type": "array",
+                "items": {
+                    "type": "object",
+                    "properties": {
+                        "id": {
+                            "type": "string",
+                            "pattern": "^[a-z][a-z0-9_-]*$",
+                            "maxLength": EXTRACT.field_id_max,
+                            "description": "Field name, e.g. 'price' or 'version'.",
+                        },
+                        "pattern": {
+                            "type": "string",
+                            "minLength": EXTRACT.pattern_min,
+                            "maxLength": EXTRACT.pattern_max,
+                            "description": "JavaScript regex source (without delimiters) that matches candidate "
+                            "values. Runs in a sandboxed worker with a hard timeout.",
+                        },
+                        "flags": {
+                            "type": "string",
+                            "maxLength": EXTRACT.flags_max,
+                            "description": "Regex flags (e.g. 'i'). 'g' is always added; non-letters are dropped.",
+                        },
+                        "description": {
+                            "type": "string",
+                            "minLength": EXTRACT.description_min,
+                            "maxLength": EXTRACT.description_max,
+                            "description": "What the field is, so Jev can pick the right candidate among regex "
+                            "matches.",
+                        },
+                    },
+                    "required": ["id", "pattern", "description"],
+                    "additionalProperties": False,
+                },
+                "minItems": EXTRACT.fields_min,
+                "maxItems": EXTRACT.fields_max,
+                "description": f"Fields to extract. Up to {EXTRACT.fields_max} per call, all judged in one request.",
+            },
+            "purpose": {"type": "string", "description": "What the extraction is for; shared across fields."},
+            "auto_accept": {
+                "type": "number",
+                "minimum": 0,
+                "maximum": 1,
+                "description": "Minimum top probability for auto. Default 0.85.",
+            },
+            "minimum_margin": {
+                "type": "number",
+                "minimum": 0,
+                "maximum": 1,
+                "description": "Minimum winner-to-runner-up gap for auto. Default 0.5.",
+            },
+        },
+        "required": ["document", "fields"],
+        "additionalProperties": False,
+    },
+)
+
+
+@dataclass(frozen=True, slots=True)
+class _Field:
+    id: str
+    key: str
+    pattern: str
+    description: str
+    candidates: list[str]
+    too_long: int
+    truncated: bool
+    error: str | None
+
+    @property
+    def flags(self) -> dict[str, object]:
+        return {"candidates_truncated": self.truncated, "matches_skipped_too_long": self.too_long}
+
+
+async def _match(runtime: Runtime, index: int, raw: dict[str, str], units: str) -> _Field:
+    telemetry = runtime.telemetry
+    with telemetry.span("regex.extract") as span:
+        telemetry.payload(span, "pattern", lambda: raw["pattern"])
+        found = await find_candidates(runtime.regex_executor, raw["pattern"], raw.get("flags", ""), units)
+        if isinstance(found, Refused):
+            span.attributes["outcome"] = found.outcome
+            candidates, too_long, truncated, error = [], 0, False, found.reason
+        else:
+            candidates, too_long, truncated, error = found.candidates, found.too_long, found.truncated, None
+            span.attributes.update(
+                outcome="ok", candidates=len(candidates), too_long=too_long, candidates_truncated=truncated
+            )
+    return _Field(raw["id"], f"f{index}", raw["pattern"], raw["description"], candidates, too_long, truncated, error)
+
+
+def _result(field: _Field, answer: object, auto_accept: float, minimum_margin: float) -> dict[str, object]:
+    if field.error is not None:
+        return {
+            "id": field.id,
+            "value": None,
+            "status": "invalid_pattern",
+            "reason": field.error,
+            "candidates_considered": 0,
+            **field.flags,
+        }
+    if not field.candidates:
+        decision = decide_extract_field(
+            ExtractFieldEvidence(field.too_long, field.truncated, None), threshold=auto_accept, margin=minimum_margin
+        )
+        return {
+            "id": field.id,
+            "value": None,
+            "status": decision.status,
+            "reason": decision.reason,
+            "candidates_considered": 0,
+            **field.flags,
+        }
+    keys = [f"c{j}" for j in range(len(field.candidates))] + [NONE_OF_THEM]
+    validated = validate_extract_choice(answer, keys)
+    considered = len(field.candidates)
+    if validated is None:
+        return {
+            "id": field.id,
+            "value": None,
+            "status": "invalid_response",
+            "reason": None,
+            "candidates_considered": considered,
+            **field.flags,
+        }
+    gap = margin(validated.probabilities)
+    top = top_probability(validated)
+    none_matched = validated.choice == NONE_OF_THEM
+    decision = decide_extract_field(
+        ExtractFieldEvidence(field.too_long, field.truncated, ExtractJudgment(none_matched, top, gap)),
+        threshold=auto_accept,
+        margin=minimum_margin,
+    )
+    return {
+        "id": field.id,
+        "value": None if none_matched else field.candidates[int(validated.choice[1:])],
+        "status": decision.status,
+        "reason": decision.reason,
+        "confidence": validated.confidence,
+        "top_probability": top,
+        "margin": gap,
+        "candidates_considered": considered,
+        **field.flags,
+    }
+
+
+async def handle(args: dict[str, Any], runtime: Runtime) -> ToolResult:
+    auto_accept: float = args.get("auto_accept", DEFAULT_CLASSIFY_AUTO_ACCEPT)
+    minimum_margin: float = args.get("minimum_margin", DEFAULT_MINIMUM_MARGIN)
+    # The schema rejects a document over its cap first, so only the candidate universe records a cut.
+    ledger = CapLedger()
+    document = ledger.text(args["document"], EXTRACT.document_max, "context")
+    raw_fields: list[dict[str, str]] = args["fields"]
+
+    seen: set[str] = set()
+    for raw in raw_fields:
+        if raw["id"] in seen:
+            raise ToolError(f"Duplicate field id: {raw['id']}")
+        seen.add(raw["id"])
+
+    # Fields run one after another, in caller order (ADR-0012 D5).
+    units = to_units(document)
+    fields = [await _match(runtime, index, raw, units) for index, raw in enumerate(raw_fields)]
+
+    total = sum(length(candidate) for field in fields for candidate in field.candidates)
+    if exceeds(total, EXTRACT.aggregate_candidate_units):
+        raise ToolError(
+            candidate_budget_error(total, EXTRACT.aggregate_candidate_units, "Tighten the patterns or split the call.")
+        )
+
+    # One Choice per field with candidates; the document is sent once, candidates only in their criteria.
+    questions: dict[str, Question] = {}
+    state_fields: list[dict[str, object]] = []
+    for field in fields:
+        if field.error is not None or not field.candidates:
+            continue
+        criteria: dict[str, str] = {f"c{j}": f"Candidate value: {quote(c)}" for j, c in enumerate(field.candidates)}
+        criteria[NONE_OF_THEM] = "None of the candidates is the value this field asks for"
+        questions[field.key] = ChoiceQuestion(
+            f'Which candidate is the correct value of the field "{field.id}" ({field.description}) in the document '
+            "in the state? Pick the exact substring the document presents as this field's value.",
+            criteria,
+        )
+        state_fields.append({"id": field.key, "description": field.description, "pattern": field.pattern})
+
+    # No field with candidates: nothing is asked, and the frame reports no provider (`frame`).
+    evaluation = (
+        await runtime.ask({"purpose": args.get("purpose"), "document": document, "fields": state_fields}, questions)
+        if state_fields
+        else None
+    )
+    answers = evaluation.answers if evaluation is not None else {}
+
+    results = [_result(field, answers.get(field.key), auto_accept, minimum_margin) for field in fields]
+    if any(field.truncated or field.too_long > 0 for field in fields):
+        ledger.note("context")  # an incomplete candidate universe: Policy never auto-accepts over it
+    item_actions = caller_actions(r["status"] for r in results)
+    return ToolResult(
+        frame(
+            "jev_extract",
+            evaluation,
+            {
+                "summary": {
+                    "fields": len(results),
+                    "extracted": sum(1 for r in results if r["value"] is not None),
+                    "auto": sum(1 for r in results if r["status"] == "auto"),
+                    "review": sum(1 for r in results if r["status"] == "review"),
+                    "not_found": sum(1 for r in results if r["status"] == "not_found"),
+                    "invalid": sum(1 for r in results if r["status"] in ("invalid_pattern", "invalid_response")),
+                },
+                "thresholds": {"auto_accept": auto_accept, "minimum_margin": minimum_margin},
+                "results": results,
+            },
+            model=runtime.model,
+        ),
+        action=headline(item_actions),
+        item_actions=item_actions,
+        truncated=ledger.scopes,
+    )
+
+
+TOOL = JevTool(DEFINITION, handle)

jev_mcp/tools/find.py

@@ -0,0 +1,113 @@
+"""jev_find: semantic search over candidates (`index.ts:325-392`)."""
+
+from typing import Any
+
+from jev_mcp.domain import ChoiceQuestion, NoulCriteria, NoulQuestion
+from jev_mcp.ids import ensure_unique_ids
+from jev_mcp.limits import CANDIDATES, FIND
+from jev_mcp.serialize import to_fixed
+from jev_mcp.tools.base import JevTool, Runtime, ToolResult, define, frame
+from jev_mcp.tools.common import candidates_schema
+from jev_mcp.tools.observed import exists_verdict, rank_candidates, validate_choice, validate_noul
+from jev_mcp.validation.caps import CapLedger
+
+EXISTS_CRITERIA = NoulCriteria(
+    "At least one candidate states or directly implies the answer", "No candidate addresses this"
+)
+
+DEFINITION = define(
+    "jev_find",
+    "Semantic search over candidates",
+    "Rank candidates against a plain-language query with TypeSafe Jev — no embeddings needed. One Choice scores "
+    "every candidate id by how well it answers the query, plus a Noul checks whether any candidate addresses the "
+    "query at all (so a confident 'top hit' cannot masquerade as an answer). Pattern: "
+    f"docs.typesafe.ai/cookbooks/semantic_find. Use for 'which file/note/line covers X' across up to "
+    f"{CANDIDATES.max_items} candidates.",
+    {
+        "type": "object",
+        "properties": {
+            "query": {
+                "type": "string",
+                "minLength": 1,
+                "description": "What you are looking for, in natural language.",
+            },
+            "candidates": candidates_schema(
+                f"Candidates to search. Up to {CANDIDATES.max_items} in one call; texts are truncated at "
+                f"{CANDIDATES.text_units} chars."
+            ),
+            "top_k": {
+                "type": "integer",
+                "minimum": FIND.top_k_min,
+                "maximum": FIND.top_k_max,
+                "description": f"How many ranked candidates to return. Default {FIND.top_k_default}.",
+            },
+        },
+        "required": ["query", "candidates"],
+        "additionalProperties": False,
+    },
+)
+
+
+async def handle(args: dict[str, Any], runtime: Runtime) -> ToolResult:
+    query: str = args["query"]
+    top_k = int(args.get("top_k", FIND.top_k_default))
+    ledger = CapLedger()
+    candidates = ensure_unique_ids(
+        [
+            {"id": c.get("id", ""), "text": ledger.text(c["text"], CANDIDATES.text_units, "item")}
+            for c in args["candidates"]
+        ],
+        "candidate",
+    ).items
+    ids = [str(c["id"]) for c in candidates]
+
+    questions = {
+        "best": ChoiceQuestion(f'Which candidate contains the best answer to: "{query}"?', dict.fromkeys(ids)),
+        "exists": NoulQuestion(f'Does any candidate address or answer: "{query}"?', EXISTS_CRITERIA),
+    }
+    evaluation = await runtime.ask({"query": query, "candidates": candidates}, questions)
+    exists = validate_noul(evaluation.answers.get("exists"))
+    best = validate_choice(evaluation.answers.get("best"), ids)
+
+    if exists is None or best is None:
+        # A missing answer is neither "no match" nor "no ranking": report the protocol failure.
+        return ToolResult(
+            frame(
+                "jev_find",
+                evaluation,
+                {
+                    "query": query,
+                    "status": "invalid_response",
+                    "exists": exists,
+                    "exists_verdict": None,
+                    "top": [],
+                    "reason": "missing or malformed best or exists answer; cannot rank safely",
+                },
+            ),
+            truncated=ledger.scopes,
+        )
+
+    ranked = rank_candidates(candidates, best.probabilities)[:top_k]
+    return ToolResult(
+        frame(
+            "jev_find",
+            evaluation,
+            {
+                "query": query,
+                "exists": exists,
+                "exists_verdict": exists_verdict(exists),
+                "top": [
+                    {
+                        "id": c["id"],
+                        "probability": float(to_fixed(best.probabilities.get(str(c["id"]), 0.0), 4)),
+                        "text": c["text"],
+                    }
+                    for c in ranked
+                ],
+            },
+        ),
+        truncated=ledger.scopes,
+    )
+
+
+TOOL = JevTool(DEFINITION, handle)

jev_mcp/tools/gate.py

@@ -0,0 +1,236 @@
+"""jev_gate: review a patch and verify completion claims in one call (`index.ts:1342-1495`)."""
+
+from typing import Any
+
+from jev_mcp.domain import ChoiceQuestion
+from jev_mcp.limits import GATE
+from jev_mcp.policy import Action, ClaimJudgment, ClaimVerdict
+from jev_mcp.serialize import js_number_to_locale_string_en_us
+from jev_mcp.text import length
+from jev_mcp.tools.arguments import Refinement
+from jev_mcp.tools.base import JevTool, Runtime, ToolResult, define, frame
+from jev_mcp.tools.common import EVIDENCE_SCHEMA, has_non_empty_evidence, normalize_evidence
+from jev_mcp.tools.observed import (
+    claim_action,
+    gate_reason_codes,
+    require_complete_context,
+    validate_choice,
+    worst_action,
+)
+from jev_mcp.tools.review import (
+    ANTI_INJECTION,
+    project_review,
+    review_docs,
+    review_questions,
+    review_settings,
+)
+from jev_mcp.validation.caps import CapLedger, exceeds, gate_evidence_aggregate_error, gate_evidence_items_error
+
+CLAIM_CRITERIA = {
+    "verified": "The evidence clearly supports the claim",
+    "contradicted": "The evidence contradicts the claim",
+    "unsupported": "The evidence neither supports nor contradicts the claim",
+}
+"""`VERIFY_CLAIM_CRITERIA` (`lib.ts:250-254`)."""
+CLAIM_VERDICTS: dict[str, ClaimVerdict] = {
+    "verified": "verified",
+    "contradicted": "contradicted",
+    "unsupported": "unsupported",
+}
+
+REVIEW_FRAMING = " Claims are assertions to check, not evidence that the patch is correct or tested."
+
+DEFINITION = define(
+    "jev_gate",
+    "Gate completion: review a patch and verify claims",
+    "Review a proposed patch and verify completion claims against supplied evidence in one TypeSafe Jev call. Auto "
+    "only when the patch review is accepted and every claim is verified at or above auto_accept. Unsupported claims "
+    "require review; confident contradictions, unknown confidence, or low confidence escalate. The request and "
+    "claims are assertions to check, never proof; put supporting diff excerpts and test logs in evidence. Evidence "
+    f"is capped at {GATE.evidence_items} items and {js_number_to_locale_string_en_us(GATE.aggregate_evidence_units)} "
+    "characters in aggregate. Does not run tests or apply changes. Use jev_review "
+    "for a patch without claims, jev_verify for claims without a patch review.",
+    {
+        "type": "object",
+        "properties": {
+            "request": {
+                "type": "string",
+                "minLength": 1,
+                "description": "What the user asked for; this is not evidence of completion.",
+            },
+            "diff": {
+                "type": "string",
+                "minLength": 1,
+                "description": f"Proposed patch, file excerpt, or change summary. Truncated at {GATE.doc_units} chars.",
+            },
+            "claims": {
+                "type": "array",
+                "items": {"type": "string", "minLength": 1},
+                "minItems": GATE.claims_min,
+                "maxItems": GATE.claims_max,
+                "description": "Completion claims to check against evidence, each truncated at "
+                f"{GATE.claim_units} chars. Up to {GATE.claims_max} per call.",
+            },
+            "evidence": EVIDENCE_SCHEMA,
+            "tests": {
+                "type": "string",
+                "description": "Reported test output for the patch review. Truncated at the same cap.",
+            },
+            "auto_accept": {
+                "type": "number",
+                "minimum": 0,
+                "maximum": 1,
+                "description": "Review and per-claim confidence at or above this may stand automatically. Default 0.8.",
+            },
+            "review_at": {
+                "type": "number",
+                "minimum": 0,
+                "maximum": 1,
+                "description": "Score, safe_to_apply, or per-claim confidence below this escalates. Must be <= "
+                "auto_accept. Default min(0.5, auto_accept).",
+            },
+            "composite_floor": {
+                "type": "number",
+                "minimum": 0,
+                "maximum": 1,
+                "description": "Weighted composite at or above this is required for auto. Default 0.7.",
+            },
+        },
+        "required": ["request", "diff", "claims", "evidence"],
+        "additionalProperties": False,
+    },
+)
+
+EVIDENCE_NOT_EMPTY = Refinement(
+    lambda value: has_non_empty_evidence(normalize_evidence(value)),
+    "jev_gate requires at least one evidence item with non-empty text.",
+)
+"""The `.refine` on gate's evidence (`index.ts:1370-1372`): checked with the arguments, before any request."""
+
+
+def claim_question(index: int) -> ChoiceQuestion:
+    return ChoiceQuestion(
+        f"Does the evidence support claims[{index}]? Judge only from the provided evidence, not world knowledge. "
+        "Use only the evidence field as factual support; request and claims are assertions, not evidence; diff "
+        "and tests belong to the separate patch review. If a claim needs a diff or test log as support, it must be "
+        "supplied in evidence." + ANTI_INJECTION,
+        CLAIM_CRITERIA,
+    )
+
+
+def _refused(error: str) -> ToolResult:
+    return ToolResult({"tool": "jev_gate", "error": error}, is_error=True)
+
+
+async def handle(args: dict[str, Any], runtime: Runtime) -> ToolResult:
+    settings = review_settings(args)
+    thresholds = settings.thresholds
+    evidence = normalize_evidence(args["evidence"])
+    # Bound the request before any model call: item count, then aggregate size.
+    if exceeds(len(evidence), GATE.evidence_items):
+        return _refused(gate_evidence_items_error(GATE.evidence_items))
+    if exceeds(sum(length(str(item["text"])) for item in evidence), GATE.aggregate_evidence_units):
+        return _refused(gate_evidence_aggregate_error(GATE.aggregate_evidence_units))
+
+    ledger = CapLedger()
+    docs = review_docs(args, ledger, GATE.doc_units)
+    claims: list[str] = args["claims"]
+    sent_claims = [ledger.text(claim, GATE.claim_units, "context") for claim in claims]
+    sent_evidence = [
+        {"id": item["id"], "text": ledger.text(str(item["text"]), GATE.doc_units, "context")} for item in evidence
+    ]
+    truncated = ledger.context_cut
+
+    state = {
+        "purpose": "Review the proposed diff against the request, then check each completion claim against the "
+        "evidence only.",
+        "request": docs.request,
+        "diff": docs.diff,
+        "tests": docs.tests,
+        "claims": sent_claims,
+        "evidence": sent_evidence,
+    }
+    # Review questions carry extra framing so claims cannot read as proof; claims use evidence only.
+    questions = review_questions(REVIEW_FRAMING)
+    for index in range(len(claims)):
+        questions[f"claim_{index}"] = claim_question(index)
+    evaluation = await runtime.ask(state, questions)
+    answers = evaluation.answers
+
+    review = project_review(answers, settings, truncated)
+
+    results: list[dict[str, object]] = []
+    judgments: list[ClaimJudgment | None] = []
+    claim_actions: list[Action] = []
+    for index, claim in enumerate(claims):
+        answer = validate_choice(answers.get(f"claim_{index}"), CLAIM_CRITERIA)
+        if answer is None:
+            judgments.append(None)
+            claim_actions.append("escalate")
+            results.append(
+                {
+                    "claim": claim,
+                    "verdict": None,
+                    "confidence": None,
+                    "probabilities": None,
+                    "action": "escalate",
+                    "status": "invalid_response",
+                }
+            )
+            continue
+        verdict = CLAIM_VERDICTS[answer.choice]
+        judgments.append(ClaimJudgment(verdict, answer.confidence))
+        action = require_complete_context(
+            claim_action(verdict, answer.confidence, thresholds.auto_accept, thresholds.review_at), truncated
+        )
+        claim_actions.append(action)
+        results.append(
+            {
+                "claim": claim,
+                "verdict": verdict,
+                "confidence": answer.confidence,
+                "probabilities": answer.probabilities,
+                "action": action,
+            }
+        )
+
+    verification_action = worst_action(claim_actions)
+    verification = {
+        "action": verification_action,
+        "summary": {
+            "verified": sum(1 for r in results if r["verdict"] == "verified"),
+            "contradicted": sum(1 for r in results if r["verdict"] == "contradicted"),
+            "unsupported": sum(1 for r in results if r["verdict"] == "unsupported"),
+            "needs_review": sum(1 for r in results if r["action"] != "auto"),
+            "invalid_response": sum(1 for r in results if r.get("status") == "invalid_response"),
+        },
+        "thresholds": {"auto_accept": thresholds.auto_accept, "review_at": thresholds.review_at},
+        "results": results,
+    }
+    action = worst_action([review.action, verification_action])
+    reason_codes = gate_reason_codes(
+        truncated=truncated,
+        review_action=review.action,
+        review_invalid=review.invalid,
+        claims=judgments,
+        action=action,
+        thresholds=thresholds,
+    )
+    return ToolResult(
+        frame(
+            "jev_gate",
+            evaluation,
+            {
+                "truncated": truncated,
+                "action": action,
+                "reason_codes": reason_codes,
+                "review": review.payload,
+                "verification": verification,
+            },
+        ),
+        action=action,
+        truncated=ledger.scopes,
+    )
+
+
+TOOL = JevTool(DEFINITION, handle, {"evidence": EVIDENCE_NOT_EMPTY})

jev_mcp/tools/observed.py

@@ -0,0 +1,69 @@
+"""Answer validators and policy functions as tools call them: each call is a span (ROADMAP P9).
+
+`jev_mcp.validation` and `jev_mcp.policy` stay pure (ADR-0002); the spans are opened here, in the
+tools layer. A validator call is a `jev.validate` span labelled with its kind and whether the answer
+was valid — a rejected answer is a fail-closed. A policy call is a `jev.policy` span labelled with
+the function and, when it returns one, the action. Tools import these callables from here, never
+from the pure packages (`tests/unit/test_telemetry.py` checks).
+"""
+
+from collections.abc import Callable
+from functools import wraps
+
+from jev_mcp import policy, validation
+from jev_mcp.telemetry import ACTIONS, span
+
+TRACED: set[str] = set()
+"""Every traced name; tools must not import these from `jev_mcp.policy` or `jev_mcp.validation`."""
+
+
+def _validator[**P, R](kind: str, validate: Callable[P, R | None]) -> Callable[P, R | None]:
+    TRACED.add(validate.__name__)
+
+    @wraps(validate)
+    def traced(*args: P.args, **kwargs: P.kwargs) -> R | None:
+        with span("jev.validate", kind=kind) as current:
+            answer = validate(*args, **kwargs)
+            current.attributes["valid"] = answer is not None
+            return answer
+
+    return traced
+
+
+def _policy[**P, R](decide: Callable[P, R]) -> Callable[P, R]:
+    TRACED.add(decide.__name__)
+
+    @wraps(decide)
+    def traced(*args: P.args, **kwargs: P.kwargs) -> R:
+        with span("jev.policy", decision=decide.__name__) as current:
+            result = decide(*args, **kwargs)
+            if isinstance(result, str) and result in ACTIONS:
+                current.attributes["action"] = result
+            return result
+
+    return traced
+
+
+validate_choice = _validator("choice", validation.validate_choice)
+validate_extract_choice = _validator("extract_choice", validation.validate_extract_choice)
+validate_noul = _validator("noul", validation.validate_noul)
+validate_score = _validator("score", validation.validate_score)
+
+claim_action = _policy(policy.claim_action)
+classification_decision = _policy(policy.classification_decision)
+contradicts_recommendation = _policy(policy.contradicts_recommendation)
+decide_extract_field = _policy(policy.decide_extract_field)
+exists_verdict = _policy(policy.exists_verdict)
+gate_reason_codes = _policy(policy.gate_reason_codes)
+min_confidence = _policy(policy.min_confidence)
+rank_candidates = _policy(policy.rank_candidates)
+require_complete_context = _policy(policy.require_complete_context)
+rerank_by_score = _policy(policy.rerank_by_score)
+resolve_policy_thresholds = _policy(policy.resolve_policy_thresholds)
+review_action = _policy(policy.review_action)
+review_composite = _policy(policy.review_composite)
+screen_fail_closed = _policy(policy.screen_fail_closed)
+screen_recommendation = _policy(policy.screen_recommendation)
+validate_policy_thresholds = _policy(policy.validate_policy_thresholds)
+verify_action = _policy(policy.verify_action)
+worst_action = _policy(policy.worst_action)