graphite-code 0.3.0__py3-none-any.whl

graphite/routing/route_pool_execution.py

@@ -0,0 +1,275 @@
+"""Single-use automatic execution coordinator for approved route pools."""
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import Any, ClassVar, Protocol
+
+from .approval import ApprovalAuthority, ApprovalError, SignedApproval
+from .contracts import PublicRecord
+from .route_pool import (
+    ApprovedRoutePool,
+    RouteAttemptEvidence,
+    RouteAuthority,
+    RoutePoolError,
+    RouteSelection,
+    select_route,
+)
+
+
+@dataclass(frozen=True, slots=True)
+class RouteExecutionEvidence(PublicRecord):
+    candidate_id: str
+    candidate_digest: str
+    attempt_ordinal: int
+    outcome_category: str
+    input_tokens: int
+    output_tokens: int
+    duration_ms: int
+    cost_microunits: int | None
+
+    _public_fields: ClassVar[tuple[str, ...]] = (
+        "candidate_id",
+        "candidate_digest",
+        "attempt_ordinal",
+        "outcome_category",
+        "input_tokens",
+        "output_tokens",
+        "duration_ms",
+        "cost_microunits",
+    )
+
+    def __post_init__(self) -> None:
+        if (
+            not isinstance(self.candidate_id, str)
+            or not self.candidate_id
+            or "\x00" in self.candidate_id
+            or len(self.candidate_id) > 256
+            or any(character.isspace() for character in self.candidate_id)
+            or not isinstance(self.candidate_digest, str)
+            or len(self.candidate_digest) != 64
+            or any(
+                character not in "0123456789abcdef"
+                for character in self.candidate_digest
+            )
+            or self.outcome_category
+            not in {
+                "succeeded",
+                "capacity_unavailable",
+                "provider_process_failure",
+                "provider_unavailable",
+                "provider_protocol",
+                "timeout",
+                "cancelled",
+            }
+            or isinstance(self.attempt_ordinal, bool)
+            or not isinstance(self.attempt_ordinal, int)
+            or not 1 <= self.attempt_ordinal <= 2
+        ):
+            raise RoutePoolError("route_evidence_invalid")
+        for value, maximum in (
+            (self.input_tokens, 262_144),
+            (self.output_tokens, 32_768),
+            (self.duration_ms, 86_400_000),
+        ):
+            if (
+                isinstance(value, bool)
+                or not isinstance(value, int)
+                or not 0 <= value <= maximum
+            ):
+                raise RoutePoolError("route_evidence_invalid")
+        if self.cost_microunits is not None and (
+            isinstance(self.cost_microunits, bool)
+            or not isinstance(self.cost_microunits, int)
+            or self.cost_microunits < 0
+            or self.cost_microunits > 10**12
+        ):
+            raise RoutePoolError("route_evidence_invalid")
+
+
+@dataclass(frozen=True, slots=True)
+class RouteExecutionResult:
+    candidate_id: str
+    candidate_digest: str
+    attempt_ordinal: int
+    output: str = field(repr=False, compare=False)
+    input_tokens: int
+    output_tokens: int
+    duration_ms: int
+    cost_microunits: int | None
+
+
+class RouteAttemptFailure(RuntimeError):
+    """Trusted adapter failure carrying sanitized evidence only."""
+
+    def __init__(self, evidence: RouteAttemptEvidence) -> None:
+        if not isinstance(evidence, RouteAttemptEvidence):
+            raise RoutePoolError("route_attempt_invalid")
+        self.evidence = evidence
+        super().__init__(evidence.failure_category)
+
+
+class AuthorityLoader(Protocol):
+    def __call__(self) -> tuple[RouteAuthority, ...]: ...
+
+
+class RouteRunner(Protocol):
+    def __call__(self, selection: RouteSelection) -> RouteExecutionResult: ...
+
+
+EvidenceSink = Callable[[RouteExecutionEvidence], Any]
+
+
+def _load_authority(loader: AuthorityLoader) -> tuple[RouteAuthority, ...]:
+    try:
+        authorities = loader()
+    except Exception:
+        raise RoutePoolError("route_authority_unavailable") from None
+    if not isinstance(authorities, tuple):
+        raise RoutePoolError("route_authority_invalid")
+    return authorities
+
+
+def _persist_evidence(
+    sink: EvidenceSink,
+    evidence: RouteExecutionEvidence,
+) -> None:
+    try:
+        sink(evidence)
+    except Exception:
+        raise RoutePoolError("route_evidence_unavailable") from None
+
+
+def _failure_evidence(
+    selection: RouteSelection,
+    failure: RouteAttemptEvidence,
+) -> RouteExecutionEvidence:
+    if (
+        failure.candidate_id != selection.candidate.candidate_id
+        or failure.candidate_digest != selection.candidate.digest
+        or failure.attempt_ordinal != selection.attempt_ordinal
+    ):
+        raise RoutePoolError("route_attempt_invalid")
+    return RouteExecutionEvidence(
+        candidate_id=failure.candidate_id,
+        candidate_digest=failure.candidate_digest,
+        attempt_ordinal=failure.attempt_ordinal,
+        outcome_category=failure.failure_category,
+        input_tokens=failure.input_tokens,
+        output_tokens=failure.output_tokens,
+        duration_ms=failure.duration_ms,
+        cost_microunits=failure.cost_microunits,
+    )
+
+
+def _validate_result(
+    pool: ApprovedRoutePool,
+    selection: RouteSelection,
+    result: RouteExecutionResult,
+) -> RouteExecutionEvidence:
+    if (
+        not isinstance(result, RouteExecutionResult)
+        or result.candidate_id != selection.candidate.candidate_id
+        or result.candidate_digest != selection.candidate.digest
+        or result.attempt_ordinal != selection.attempt_ordinal
+        or not isinstance(result.output, str)
+        or not result.output
+        or "\x00" in result.output
+        or len(result.output) > 1_048_576
+    ):
+        raise RoutePoolError("route_result_invalid")
+    values = (
+        (result.input_tokens, selection.remaining_input_tokens),
+        (result.output_tokens, selection.remaining_output_tokens),
+        (result.duration_ms, selection.remaining_duration_ms),
+    )
+    if any(
+        isinstance(value, bool)
+        or not isinstance(value, int)
+        or value < 0
+        or value > maximum
+        for value, maximum in values
+    ):
+        raise RoutePoolError("route_pool_budget_exhausted")
+    if pool.max_cost_microunits is None:
+        if result.cost_microunits is not None:
+            raise RoutePoolError("route_pool_cost_invalid")
+    elif (
+        isinstance(result.cost_microunits, bool)
+        or not isinstance(result.cost_microunits, int)
+        or result.cost_microunits < 0
+        or selection.remaining_cost_microunits is None
+        or result.cost_microunits > selection.remaining_cost_microunits
+    ):
+        raise RoutePoolError("route_pool_budget_exhausted")
+    return RouteExecutionEvidence(
+        result.candidate_id,
+        result.candidate_digest,
+        result.attempt_ordinal,
+        "succeeded",
+        result.input_tokens,
+        result.output_tokens,
+        result.duration_ms,
+        result.cost_microunits,
+    )
+
+
+def execute_approved_route_pool(
+    *,
+    pool: ApprovedRoutePool,
+    signed_approval: SignedApproval,
+    approval_authority: ApprovalAuthority,
+    authority_loader: AuthorityLoader,
+    runner: RouteRunner,
+    evidence_sink: EvidenceSink,
+    repository_quota_tokens: int,
+    machine_quota_tokens: int,
+    now: Callable[[], int],
+) -> RouteExecutionResult:
+    """Consume one pool and automatically advance once on safe capacity failure."""
+    if (
+        not isinstance(pool, ApprovedRoutePool)
+        or not isinstance(approval_authority, ApprovalAuthority)
+        or not callable(authority_loader)
+        or not callable(runner)
+        or not callable(evidence_sink)
+        or not callable(now)
+    ):
+        raise RoutePoolError("route_execution_invalid")
+    try:
+        approval_authority.consume(
+            signed_approval,
+            pool,
+            repository_quota_tokens=repository_quota_tokens,
+            machine_quota_tokens=machine_quota_tokens,
+        )
+    except ApprovalError:
+        raise
+    attempts: list[RouteAttemptEvidence] = []
+    while len(attempts) < pool.max_attempts:
+        try:
+            current_time = now()
+        except Exception:
+            raise RoutePoolError("route_pool_time_invalid") from None
+        selection = select_route(
+            pool,
+            _load_authority(authority_loader),
+            tuple(attempts),
+            now=current_time,
+        )
+        try:
+            result = runner(selection)
+        except RouteAttemptFailure as exc:
+            failure = exc.evidence
+            evidence = _failure_evidence(selection, failure)
+            _persist_evidence(evidence_sink, evidence)
+            attempts.append(failure)
+            if len(attempts) >= pool.max_attempts:
+                raise RoutePoolError("route_pool_attempts_exhausted") from None
+            continue
+        except Exception:
+            raise RoutePoolError("route_attempt_failed") from None
+        evidence = _validate_result(pool, selection, result)
+        _persist_evidence(evidence_sink, evidence)
+        return result
+    raise RoutePoolError("route_pool_attempts_exhausted")

graphite/routing/schema_validation.py

@@ -0,0 +1,169 @@
+"""Minimal in-house JSON-Schema validator for governed structured output.
+
+The governed output schemas are sha256-pinned constants (not attacker input), so this
+validator's job is to enforce the constraints those schemas express, not to police keyword
+novelty. It therefore fails closed ONLY on combinator keywords (anyOf/oneOf/allOf/not/$ref/
+patternProperties/...) -- keywords that change what "valid" means and that this validator
+cannot safely approximate. All other (refinement/annotation) keywords are tolerated:
+matches_schema enforces the ones it understands and ignores the rest, which can only
+under-enforce a single constraint, never accept a structurally wrong shape. Zero third-party
+dependencies by design.
+"""
+from __future__ import annotations
+
+import re
+
+# Keywords that combine/redirect subschemas and thus change what "valid" means. This
+# validator cannot approximate them, so a schema using any of them fails closed at
+# is_supported_schema -> the executor rejects it with request_invalid before any call,
+# rather than being silently under-validated.
+_COMBINATORS = frozenset({
+    "anyOf", "oneOf", "allOf", "not", "$ref", "$dynamicRef",
+    "if", "then", "else", "patternProperties", "propertyNames",
+    "dependencies", "dependentSchemas", "dependentRequired",
+    "unevaluatedProperties", "unevaluatedItems", "contains",
+    "prefixItems", "additionalItems",
+})
+
+
+def is_supported_schema(schema: object) -> bool:
+    """True unless the schema uses a combinator keyword this validator cannot safely
+    approximate (or a non-bool additionalProperties, which is a schema-valued shape
+    change). Refinement/annotation keywords are tolerated. Governed schemas are pinned
+    constants, so this gate catches a shape we would mis-validate, not unknown-but-harmless
+    keys."""
+    if not isinstance(schema, dict) or not schema:
+        return False
+    if not _COMBINATORS.isdisjoint(schema):
+        return False
+    if not isinstance(schema.get("additionalProperties", False), bool):
+        return False
+    pattern = schema.get("pattern")
+    if isinstance(pattern, str):
+        try:
+            re.compile(pattern)
+        except re.error:
+            return False
+    properties = schema.get("properties")
+    if properties is not None:
+        if not isinstance(properties, dict):
+            return False
+        if not all(isinstance(k, str) and is_supported_schema(v) for k, v in properties.items()):
+            return False
+    items = schema.get("items")
+    if items is not None and not is_supported_schema(items):
+        return False
+    return True
+
+
+def matches_schema(value: object, schema: object) -> bool:
+    """True iff value conforms to every constraint in schema that this validator
+    understands; unknown refinement keywords are ignored (never over-reject).
+
+    Precondition: schema must already have passed is_supported_schema -- callers gate the
+    schema once, then match many values against it. Given such a schema this never raises.
+    Untrusted VALUES are always handled safely: a non-conforming (or wrong-typed) value
+    returns False, never raises.
+    """
+    if not isinstance(schema, dict):
+        return False
+    type_value = schema.get("type")
+    if type_value is not None and not _matches_type(value, type_value):
+        return False
+    if "const" in schema and not _json_equal(value, schema["const"]):
+        return False
+    if "enum" in schema and not any(_json_equal(value, member) for member in schema["enum"]):
+        return False
+    if isinstance(value, str) and not _matches_string(value, schema):
+        return False
+    if isinstance(value, dict) and _is_object_schema(schema) and not _matches_object(value, schema):
+        return False
+    if isinstance(value, list) and _is_array_schema(schema) and not _matches_array(value, schema):
+        return False
+    return True
+
+
+def _is_object_schema(schema: dict) -> bool:
+    return schema.get("type") == "object" or any(
+        key in schema for key in ("properties", "required", "additionalProperties")
+    )
+
+
+def _is_array_schema(schema: dict) -> bool:
+    return schema.get("type") == "array" or any(
+        key in schema for key in ("items", "minItems", "maxItems")
+    )
+
+
+def _matches_string(value: str, schema: dict) -> bool:
+    pattern = schema.get("pattern")
+    if isinstance(pattern, str) and re.fullmatch(pattern, value) is None:
+        return False
+    maximum = schema.get("maxLength")
+    if _is_bound(maximum) and len(value) > maximum:
+        return False
+    minimum = schema.get("minLength")
+    if _is_bound(minimum) and len(value) < minimum:
+        return False
+    return True
+
+
+def _matches_object(value: dict, schema: dict) -> bool:
+    properties = schema.get("properties", {})
+    if not isinstance(properties, dict):
+        return False
+    if not all(key in value for key in schema.get("required", [])):
+        return False
+    if schema.get("additionalProperties", False) is False and not set(value) <= set(properties):
+        return False
+    return all(
+        matches_schema(value[key], subschema)
+        for key, subschema in properties.items()
+        if key in value
+    )
+
+
+def _matches_array(value: list, schema: dict) -> bool:
+    minimum = schema.get("minItems")
+    if _is_bound(minimum) and len(value) < minimum:
+        return False
+    maximum = schema.get("maxItems")
+    if _is_bound(maximum) and len(value) > maximum:
+        return False
+    items = schema.get("items")
+    if isinstance(items, dict):
+        return all(matches_schema(element, items) for element in value)
+    return True
+
+
+def _is_bound(value: object) -> bool:
+    return isinstance(value, int) and not isinstance(value, bool) and value >= 0
+
+
+def _matches_type(value: object, type_value: object) -> bool:
+    if isinstance(type_value, list):
+        return any(_matches_type(value, member) for member in type_value)
+    if type_value == "string":
+        return isinstance(value, str)
+    if type_value == "integer":
+        return isinstance(value, int) and not isinstance(value, bool)
+    if type_value == "number":
+        return isinstance(value, (int, float)) and not isinstance(value, bool)
+    if type_value == "boolean":
+        return isinstance(value, bool)
+    if type_value == "null":
+        return value is None
+    if type_value == "object":
+        return isinstance(value, dict)
+    if type_value == "array":
+        return isinstance(value, list)
+    return False
+
+
+def _json_equal(value: object, target: object) -> bool:
+    """Equality that does not conflate True==1, 1==1.0, or 1.0==1 (JSON-kind aware)."""
+    if isinstance(value, bool) or isinstance(target, bool):
+        return value is target
+    if isinstance(value, (int, float)) and isinstance(target, (int, float)):
+        return type(value) is type(target) and value == target
+    return value == target