agentevolve-optimizer 0.5.0__py3-none-any.whl

agent_evolve/application/gated_agentic_generator.py

@@ -0,0 +1,205 @@
+"""Fail-closed telemetry policy before a successful agentic call can be used.
+
+The provider queue durably publishes terminal metadata first.  This decorator
+then verifies the scientific route and per-call resource envelope before an
+``AgenticEvolutionEngine`` may materialize or physically evaluate the proposal.
+Per-call aggregate ceilings avoid completion-order-dependent selective
+acceptance: with a separate hard logical-call cap, their product is a
+deterministic run ceiling.  Reasoning usage is part of aggregate output usage;
+an independent reasoning ceiling is enforced only when the selected route
+actually guarantees one.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass
+from decimal import Decimal
+
+from agent_evolve.ports.agentic_generator import (
+    AgenticCallTelemetry,
+    AgenticGenerator,
+    ReflectionGenerationRequest,
+    ReflectionGenerationResult,
+    VariationGenerationRequest,
+    VariationGenerationResult,
+)
+
+
+class AgenticTelemetryRejected(RuntimeError):
+    """A sanitized rejection that never includes prompts or model output."""
+
+    def __init__(self, reason: str) -> None:
+        if type(reason) is not str or not reason:
+            raise ValueError("rejection reason must be non-empty")
+        super().__init__(f"agentic response telemetry rejected: {reason}")
+        self.reason = reason
+
+
+def _canonical_json(value: object) -> bytes:
+    return json.dumps(
+        value,
+        ensure_ascii=True,
+        allow_nan=False,
+        separators=(",", ":"),
+        sort_keys=True,
+    ).encode("ascii")
+
+
+@dataclass(frozen=True, slots=True)
+class AgenticTelemetryPolicy:
+    """Exact provider/model identity and one-call token/cost bounds."""
+
+    requested_model: str
+    allowed_resolved_models: tuple[str, ...]
+    allowed_resolved_providers: tuple[str, ...]
+    max_cost_usd: Decimal
+    max_input_tokens: int
+    max_output_tokens: int
+    max_reasoning_tokens: int | None
+    max_attempt_count: int
+
+    policy_id = "exact_agentic_telemetry_gate"
+    policy_version = 3
+    reasoning_token_accounting = "included_in_output_tokens"
+
+    def __post_init__(self) -> None:
+        for name in ("requested_model",):
+            value = getattr(self, name)
+            if type(value) is not str or not value or value != value.strip():
+                raise ValueError(f"{name} must be canonical non-empty text")
+        for name in ("allowed_resolved_models", "allowed_resolved_providers"):
+            values = getattr(self, name)
+            if (
+                type(values) is not tuple
+                or not values
+                or any(
+                    type(value) is not str or not value or value != value.strip()
+                    for value in values
+                )
+            ):
+                raise ValueError(f"{name} must be non-empty canonical text")
+            if len(set(values)) != len(values):
+                raise ValueError(f"{name} cannot contain duplicates")
+        if any("/" not in value for value in self.allowed_resolved_models):
+            raise ValueError("allowed_resolved_models must contain model slugs")
+        if type(self.max_cost_usd) is not Decimal:
+            raise TypeError("max_cost_usd must be an exact Decimal")
+        if not self.max_cost_usd.is_finite() or self.max_cost_usd < 0:
+            raise ValueError("max_cost_usd must be finite and non-negative")
+        for name in (
+            "max_input_tokens",
+            "max_output_tokens",
+            "max_attempt_count",
+        ):
+            value = getattr(self, name)
+            if type(value) is not int or value < 0:
+                raise ValueError(f"{name} must be a non-negative integer")
+        if self.max_reasoning_tokens is not None and (
+            type(self.max_reasoning_tokens) is not int
+            or self.max_reasoning_tokens < 0
+        ):
+            raise ValueError(
+                "max_reasoning_tokens must be a non-negative integer or None"
+            )
+        if self.max_attempt_count == 0:
+            raise ValueError("max_attempt_count must be positive")
+
+    def to_trace_record(self) -> dict[str, object]:
+        return {
+            "policy_id": self.policy_id,
+            "policy_version": self.policy_version,
+            "requested_model": self.requested_model,
+            "allowed_resolved_models": list(self.allowed_resolved_models),
+            "allowed_resolved_providers": list(self.allowed_resolved_providers),
+            "max_cost_usd": str(self.max_cost_usd),
+            "max_input_tokens": self.max_input_tokens,
+            "max_output_tokens": self.max_output_tokens,
+            "max_reasoning_tokens": self.max_reasoning_tokens,
+            "reasoning_token_accounting": self.reasoning_token_accounting,
+            "max_attempt_count": self.max_attempt_count,
+        }
+
+    @property
+    def policy_sha256(self) -> str:
+        return hashlib.sha256(
+            b"agent-evolve:agentic-telemetry-policy:v3\x00"
+            + _canonical_json(self.to_trace_record())
+        ).hexdigest()
+
+    def validate(self, telemetry: AgenticCallTelemetry) -> None:
+        if type(telemetry) is not AgenticCallTelemetry:
+            raise TypeError("telemetry must be an exact AgenticCallTelemetry")
+        AgenticCallTelemetry.__post_init__(telemetry)
+        if telemetry.reasoning_tokens > telemetry.output_tokens:
+            raise AgenticTelemetryRejected("reasoning_output_accounting")
+        checks = (
+            (telemetry.requested_model == self.requested_model, "requested_model"),
+            (
+                telemetry.resolved_model in self.allowed_resolved_models,
+                "resolved_model",
+            ),
+            (
+                telemetry.resolved_provider in self.allowed_resolved_providers,
+                "resolved_provider",
+            ),
+            (telemetry.input_tokens <= self.max_input_tokens, "input_tokens"),
+            (telemetry.output_tokens <= self.max_output_tokens, "output_tokens"),
+            (telemetry.attempt_count <= self.max_attempt_count, "attempt_count"),
+        )
+        for accepted, reason in checks:
+            if not accepted:
+                raise AgenticTelemetryRejected(reason)
+        if (
+            self.max_reasoning_tokens is not None
+            and telemetry.reasoning_tokens > self.max_reasoning_tokens
+        ):
+            raise AgenticTelemetryRejected("reasoning_tokens")
+        cost = telemetry.cost_usd
+        if cost is None:
+            raise AgenticTelemetryRejected("missing_cost")
+        if type(cost) is not Decimal:
+            raise AgenticTelemetryRejected("non_decimal_cost")
+        if not cost.is_finite() or cost < 0:
+            raise AgenticTelemetryRejected("invalid_cost")
+        if cost > self.max_cost_usd:
+            raise AgenticTelemetryRejected("cost_ceiling")
+
+
+class TelemetryGatedAgenticGenerator:
+    """Transparent generator decorator with a pre-evaluation telemetry gate."""
+
+    def __init__(self, generator: AgenticGenerator, policy: AgenticTelemetryPolicy):
+        if not isinstance(generator, AgenticGenerator):
+            raise TypeError("generator must implement AgenticGenerator")
+        if type(policy) is not AgenticTelemetryPolicy:
+            raise TypeError("policy must be an exact AgenticTelemetryPolicy")
+        AgenticTelemetryPolicy.__post_init__(policy)
+        self.generator = generator
+        self.policy = policy
+
+    async def propose(
+        self, request: VariationGenerationRequest
+    ) -> VariationGenerationResult:
+        result = await self.generator.propose(request)
+        if type(result) is not VariationGenerationResult:
+            raise TypeError("generator returned a non-variation result")
+        self.policy.validate(result.telemetry)
+        return result
+
+    async def reflect(
+        self, request: ReflectionGenerationRequest
+    ) -> ReflectionGenerationResult:
+        result = await self.generator.reflect(request)
+        if type(result) is not ReflectionGenerationResult:
+            raise TypeError("generator returned a non-reflection result")
+        self.policy.validate(result.telemetry)
+        return result
+
+
+__all__ = [
+    "AgenticTelemetryPolicy",
+    "AgenticTelemetryRejected",
+    "TelemetryGatedAgenticGenerator",
+]

agent_evolve/application/generation_feedback.py

@@ -0,0 +1,293 @@
+"""Budgeted inter-generation feedback contracts.
+
+The optimizer owns admission and accounting, while an injected interceptor owns
+the feedback behavior (for example, trace reflection or memory curation).  A
+reservation is frozen before a generation starts.  The interceptor is invoked
+only after that generation's receipt has been sealed, so the next planner call
+can observe its effects without allowing feedback to alter in-flight evidence.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from agent_evolve.application.budgeted_optimizer import (
+        GenerationPlan,
+        GenerationReceipt,
+        OptimizerState,
+    )
+
+
+_POLICY_ID = re.compile(r"^[a-z][a-z0-9_.-]{0,95}$")
+_HASH_DOMAIN = b"agent-evolve:generation-feedback:v1\x00"
+
+
+def _canonical_json(value: object) -> bytes:
+    return json.dumps(
+        value,
+        ensure_ascii=True,
+        allow_nan=False,
+        separators=(",", ":"),
+        sort_keys=True,
+    ).encode("ascii")
+
+
+def _record_hash(kind: str, value: object) -> str:
+    return hashlib.sha256(
+        _HASH_DOMAIN + kind.encode("ascii") + b"\x00" + _canonical_json(value)
+    ).hexdigest()
+
+
+def _validate_metadata(value: tuple[tuple[str, str], ...], *, name: str) -> None:
+    if type(value) is not tuple:
+        raise TypeError(f"{name} must be an exact tuple")
+    for item in value:
+        if (
+            type(item) is not tuple
+            or len(item) != 2
+            or any(type(part) is not str or not part for part in item)
+        ):
+            raise TypeError(f"{name} must contain non-empty exact string pairs")
+    if value != tuple(sorted(set(value))):
+        raise ValueError(f"{name} must be unique and canonically sorted")
+
+
+@dataclass(frozen=True, slots=True)
+class GenerationFeedbackReservation:
+    """Pre-generation upper bound for one interceptor invocation."""
+
+    policy_id: str
+    policy_version: int
+    logical_llm_calls: int
+    metadata: tuple[tuple[str, str], ...] = ()
+
+    def __post_init__(self) -> None:
+        if (
+            type(self.policy_id) is not str
+            or _POLICY_ID.fullmatch(self.policy_id) is None
+        ):
+            raise ValueError("policy_id must use the closed lowercase token grammar")
+        if type(self.policy_version) is not int or self.policy_version <= 0:
+            raise ValueError("policy_version must be a positive exact integer")
+        if type(self.logical_llm_calls) is not int or self.logical_llm_calls < 0:
+            raise ValueError("logical_llm_calls must be a non-negative exact integer")
+        _validate_metadata(self.metadata, name="metadata")
+
+    def to_record(self) -> dict[str, object]:
+        return {
+            "policy_id": self.policy_id,
+            "policy_version": self.policy_version,
+            "logical_llm_calls": self.logical_llm_calls,
+            "metadata": [list(item) for item in self.metadata],
+        }
+
+    @property
+    def reservation_hash(self) -> str:
+        return _record_hash("reservation", self.to_record())
+
+
+@dataclass(frozen=True, slots=True)
+class GenerationFeedbackContext:
+    """Immutable post-generation evidence exposed to an interceptor."""
+
+    state: OptimizerState
+    plan: GenerationPlan
+    generation_receipt: GenerationReceipt
+    reservation: GenerationFeedbackReservation
+
+    def __post_init__(self) -> None:
+        if type(self.reservation) is not GenerationFeedbackReservation:
+            raise TypeError(
+                "reservation must be an exact GenerationFeedbackReservation"
+            )
+        if self.state.generation != self.plan.generation:
+            raise ValueError("feedback state and plan generations differ")
+        if self.generation_receipt.generation != self.plan.generation:
+            raise ValueError("feedback receipt and plan generations differ")
+        if not self.state.generation_receipts:
+            raise ValueError("feedback state has no sealed generation receipt")
+        if self.state.generation_receipts[-1] != self.generation_receipt:
+            raise ValueError(
+                "feedback must observe the latest sealed generation receipt"
+            )
+
+
+@dataclass(frozen=True, slots=True)
+class GenerationFeedbackResult:
+    """Interceptor-declared consumption and content-free result metadata."""
+
+    logical_llm_calls_used: int
+    metadata: tuple[tuple[str, str], ...] = ()
+
+    def __post_init__(self) -> None:
+        if (
+            type(self.logical_llm_calls_used) is not int
+            or self.logical_llm_calls_used < 0
+        ):
+            raise ValueError(
+                "logical_llm_calls_used must be a non-negative exact integer"
+            )
+        _validate_metadata(self.metadata, name="metadata")
+
+
+@dataclass(frozen=True, slots=True)
+class GenerationFeedbackReceipt:
+    """Authenticated accounting record for one completed interceptor call."""
+
+    generation: int
+    policy_id: str
+    policy_version: int
+    reservation_hash: str
+    generation_receipt_hash: str
+    logical_llm_calls_before: int
+    logical_llm_calls_after: int
+    reserved_logical_llm_calls: int
+    used_logical_llm_calls: int
+    result_metadata: tuple[tuple[str, str], ...]
+    receipt_hash: str
+
+    def __post_init__(self) -> None:
+        if type(self.generation) is not int or self.generation <= 0:
+            raise ValueError("generation must be a positive exact integer")
+        if (
+            type(self.policy_id) is not str
+            or _POLICY_ID.fullmatch(self.policy_id) is None
+        ):
+            raise ValueError("policy_id must use the closed lowercase token grammar")
+        if type(self.policy_version) is not int or self.policy_version <= 0:
+            raise ValueError("policy_version must be a positive exact integer")
+        for name in ("reservation_hash", "generation_receipt_hash", "receipt_hash"):
+            value = getattr(self, name)
+            if type(value) is not str or re.fullmatch(r"[0-9a-f]{64}", value) is None:
+                raise ValueError(f"{name} must be a lowercase SHA-256 digest")
+        for name in (
+            "logical_llm_calls_before",
+            "logical_llm_calls_after",
+            "reserved_logical_llm_calls",
+            "used_logical_llm_calls",
+        ):
+            value = getattr(self, name)
+            if type(value) is not int or value < 0:
+                raise ValueError(f"{name} must be a non-negative exact integer")
+        if self.used_logical_llm_calls > self.reserved_logical_llm_calls:
+            raise ValueError("used feedback calls cannot exceed the reservation")
+        if self.logical_llm_calls_after - self.logical_llm_calls_before != (
+            self.used_logical_llm_calls
+        ):
+            raise ValueError("feedback counters differ from declared consumption")
+        _validate_metadata(self.result_metadata, name="result_metadata")
+
+
+def _receipt_record(receipt: GenerationFeedbackReceipt) -> dict[str, object]:
+    return {
+        "generation": receipt.generation,
+        "policy_id": receipt.policy_id,
+        "policy_version": receipt.policy_version,
+        "reservation_hash": receipt.reservation_hash,
+        "generation_receipt_hash": receipt.generation_receipt_hash,
+        "logical_llm_calls_before": receipt.logical_llm_calls_before,
+        "logical_llm_calls_after": receipt.logical_llm_calls_after,
+        "reserved_logical_llm_calls": receipt.reserved_logical_llm_calls,
+        "used_logical_llm_calls": receipt.used_logical_llm_calls,
+        "result_metadata": [list(item) for item in receipt.result_metadata],
+    }
+
+
+def generation_feedback_receipt_hash(receipt: GenerationFeedbackReceipt) -> str:
+    """Recompute the canonical feedback receipt identity."""
+
+    if type(receipt) is not GenerationFeedbackReceipt:
+        raise TypeError("receipt must be an exact GenerationFeedbackReceipt")
+    return _record_hash("receipt", _receipt_record(receipt))
+
+
+def validate_generation_feedback_receipt(
+    receipt: GenerationFeedbackReceipt,
+) -> None:
+    """Fail closed unless a feedback receipt authenticates its contents."""
+
+    if type(receipt) is not GenerationFeedbackReceipt:
+        raise TypeError("receipt must be an exact GenerationFeedbackReceipt")
+    GenerationFeedbackReceipt.__post_init__(receipt)
+    if generation_feedback_receipt_hash(receipt) != receipt.receipt_hash:
+        raise ValueError("feedback receipt hash does not authenticate its contents")
+
+
+def seal_generation_feedback(
+    *,
+    context: GenerationFeedbackContext,
+    result: GenerationFeedbackResult,
+) -> GenerationFeedbackReceipt:
+    """Validate exact consumption and seal the feedback accounting record."""
+
+    if type(context) is not GenerationFeedbackContext:
+        raise TypeError("context must be an exact GenerationFeedbackContext")
+    GenerationFeedbackContext.__post_init__(context)
+    if type(result) is not GenerationFeedbackResult:
+        raise TypeError("result must be an exact GenerationFeedbackResult")
+    GenerationFeedbackResult.__post_init__(result)
+    reservation = context.reservation
+    if result.logical_llm_calls_used > reservation.logical_llm_calls:
+        raise ValueError("feedback consumption exceeds its pre-generation reservation")
+    before = context.state.logical_llm_calls
+    after = before + result.logical_llm_calls_used
+    provisional = GenerationFeedbackReceipt(
+        generation=context.plan.generation,
+        policy_id=reservation.policy_id,
+        policy_version=reservation.policy_version,
+        reservation_hash=reservation.reservation_hash,
+        generation_receipt_hash=context.generation_receipt.receipt_hash,
+        logical_llm_calls_before=before,
+        logical_llm_calls_after=after,
+        reserved_logical_llm_calls=reservation.logical_llm_calls,
+        used_logical_llm_calls=result.logical_llm_calls_used,
+        result_metadata=result.metadata,
+        receipt_hash="0" * 64,
+    )
+    return GenerationFeedbackReceipt(
+        generation=provisional.generation,
+        policy_id=provisional.policy_id,
+        policy_version=provisional.policy_version,
+        reservation_hash=provisional.reservation_hash,
+        generation_receipt_hash=provisional.generation_receipt_hash,
+        logical_llm_calls_before=provisional.logical_llm_calls_before,
+        logical_llm_calls_after=provisional.logical_llm_calls_after,
+        reserved_logical_llm_calls=provisional.reserved_logical_llm_calls,
+        used_logical_llm_calls=provisional.used_logical_llm_calls,
+        result_metadata=provisional.result_metadata,
+        receipt_hash=_record_hash("receipt", _receipt_record(provisional)),
+    )
+
+
+@runtime_checkable
+class GenerationFeedbackInterceptor(Protocol):
+    """Optional feedback behavior injected between sealed generations."""
+
+    def reserve(
+        self,
+        *,
+        state: OptimizerState,
+        plan: GenerationPlan,
+    ) -> GenerationFeedbackReservation: ...
+
+    async def after_generation(
+        self,
+        context: GenerationFeedbackContext,
+    ) -> GenerationFeedbackResult: ...
+
+
+__all__ = [
+    "GenerationFeedbackContext",
+    "GenerationFeedbackInterceptor",
+    "GenerationFeedbackReceipt",
+    "GenerationFeedbackReservation",
+    "GenerationFeedbackResult",
+    "generation_feedback_receipt_hash",
+    "seal_generation_feedback",
+    "validate_generation_feedback_receipt",
+]

agent_evolve/application/generative_proposal_journal.py

@@ -0,0 +1,185 @@
+"""The durable side of a generative seal: one chained JSONL per campaign.
+
+One line per model call, in issue order, each carrying the digest of the line
+before it. Reading it back reconstructs the exact call sequence and re-derives
+every digest, so a journal that has been edited, reordered, truncated at the
+front, or had a call inserted into it fails to close.
+
+The last property is the one that matters most here. An agent on this project
+filled unevaluated compositions with predicted values and reported a 1.7x win
+that had to be retracted. A chained journal makes the analogous move on the
+proposal side impossible to do quietly: a call that did not happen has no
+predecessor digest to inherit, and the terminal digest of the campaign is
+published with the result.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from pathlib import Path
+from typing import Any, Iterable, Sequence
+
+from agent_evolve.domain.generative_emission import (
+    GenerativeEmission,
+    GenerativeProposalCall,
+    SealedGuidanceCall,
+    SealedRunHeader,
+    chain_sealed_calls,
+)
+from agent_evolve.domain.typed_json import freeze_json
+
+__all__ = [
+    "candidate_schema_sha256",
+    "journal_line",
+    "read_generative_journal",
+    "verify_generative_journal",
+    "write_generative_journal",
+]
+
+_SCHEMA_HASH_DOMAIN = b"agent-evolve:candidate-schema-identity:v1\x00"
+
+
+def candidate_schema_sha256(candidate_model: Any) -> str:
+    """Digest the exact JSON schema a proposal must satisfy.
+
+    This is the support of the generative operator, and therefore the support a
+    matched null has to sample. Recording it turns "the null draws from the same
+    space" from a claim in a write-up into a field two runs can be compared on.
+    """
+
+    if candidate_model is None:
+        raise ValueError(
+            "a generative campaign needs a candidate schema. Without one the "
+            "proposer has no declared support and no null can be matched to it."
+        )
+    schema = candidate_model.model_json_schema()
+    payload = json.dumps(
+        schema, sort_keys=True, separators=(",", ":"), ensure_ascii=True
+    ).encode("ascii")
+    return hashlib.sha256(_SCHEMA_HASH_DOMAIN + payload).hexdigest()
+
+
+def journal_line(record: dict) -> str:
+    """Serialise one sealed call as canonical JSON on a single line."""
+
+    return json.dumps(
+        record, sort_keys=True, separators=(",", ":"), ensure_ascii=True, allow_nan=False
+    )
+
+
+def write_generative_journal(path: Path, calls: Sequence[Any]) -> str:
+    """Write the chain and return its terminal digest."""
+
+    terminal = chain_sealed_calls(tuple(calls))
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("w", encoding="ascii") as handle:
+        for call in calls:
+            handle.write(journal_line(call.to_record()) + "\n")
+    return terminal
+
+
+def _call_from_record(record: dict) -> Any:
+    if record.get("schema_version") != 1:
+        raise ValueError("unsupported sealed call schema_version")
+    kind = record.get("record_kind")
+    if kind == "run_header":
+        call = SealedRunHeader(
+            proposer_id=str(record["proposer_id"]),
+            requested_model=str(record["requested_model"]),
+            candidate_schema_sha256=str(record["candidate_schema_sha256"]),
+            provides_insights=bool(record["provides_insights"]),
+        )
+    elif "emissions" in record:
+        emissions = tuple(
+            GenerativeEmission(
+                configuration=freeze_json(dict(item["configuration"])),
+                accepted=bool(item["accepted"]),
+                rejection_reason=str(item.get("rejection_reason", "")),
+            )
+            for item in record["emissions"]
+        )
+        call = GenerativeProposalCall(
+            call_ordinal=int(record["call_ordinal"]),
+            op=str(record["op"]),
+            requested_model=str(record["requested_model"]),
+            prompt_sha256=str(record["prompt_sha256"]),
+            candidate_schema_sha256=str(record["candidate_schema_sha256"]),
+            emissions=emissions,
+            previous_call_sha256=str(record["previous_call_sha256"]),
+        )
+    elif "outputs" in record:
+        call = SealedGuidanceCall(
+            call_ordinal=int(record["call_ordinal"]),
+            op=str(record["op"]),
+            requested_model=str(record["requested_model"]),
+            prompt_sha256=str(record["prompt_sha256"]),
+            outputs=tuple(str(x) for x in record["outputs"]),
+            previous_call_sha256=str(record["previous_call_sha256"]),
+        )
+    else:
+        raise ValueError("a sealed call carries either emissions or outputs")
+    if call.identity_sha256 != record["call_identity_sha256"]:
+        raise ValueError(
+            f"call {record['call_ordinal']} does not authenticate: its recorded "
+            "identity is not the identity of its contents"
+        )
+    return call
+
+
+def read_generative_journal(path: Path) -> tuple:
+    """Read a journal back into sealed call objects, authenticating each line."""
+
+    calls = []
+    with path.open("r", encoding="ascii") as handle:
+        for line in handle:
+            if not line.strip():
+                continue
+            calls.append(_call_from_record(json.loads(line)))
+    return tuple(calls)
+
+
+def verify_generative_journal(path: Path) -> dict:
+    """Authenticate a journal end to end and summarise what it says happened.
+
+    Every count here is derived from the sealed content. Nothing is declared.
+    """
+
+    calls = read_generative_journal(path)
+    terminal = chain_sealed_calls(calls)
+    header = calls[0]
+    proposals = tuple(c for c in calls if type(c) is GenerativeProposalCall)
+    emitted = sum(len(c.emissions) for c in proposals)
+    accepted = sum(1 for c in proposals for e in c.emissions if e.accepted)
+    distinct = {
+        e.configuration_sha256 for c in proposals for e in c.emissions if e.accepted
+    }
+    schemas = {c.candidate_schema_sha256 for c in proposals}
+    models = {c.requested_model for c in calls}
+    return {
+        "path": str(path),
+        "terminal_sha256": terminal,
+        "proposer_id": header.proposer_id,
+        "provides_insights": header.provides_insights,
+        "calls": len(calls) - 1,
+        "proposal_calls": len(proposals),
+        "guidance_calls": len(calls) - 1 - len(proposals),
+        "emitted_configurations": emitted,
+        "accepted_configurations": accepted,
+        "distinct_accepted_configurations": len(distinct),
+        "candidate_schema_sha256s": sorted(schemas),
+        "requested_models": sorted(models),
+    }
+
+
+def iter_accepted_configurations(calls: Iterable[Any]) -> tuple:
+    """Every configuration the model authored that ``validate`` let through."""
+
+    out = []
+    for call in calls:
+        if type(call) is not GenerativeProposalCall:
+            continue
+        for emission in call.emissions:
+            if emission.accepted:
+                out.append(emission.configuration)
+    return tuple(out)