agentevolve-optimizer 0.5.0__py3-none-any.whl

agent_evolve/application/outcome_relation.py

@@ -0,0 +1,193 @@
+"""Injected, stateless relations over sealed detailed evaluation evidence."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass
+from enum import Enum
+
+from agent_evolve.application.detailed_evaluation import DetailedEvaluation
+from agent_evolve.core.problem import (
+    ObjectiveSpec,
+    normalize_objective_values,
+    validate_objective_specs,
+)
+from agent_evolve.domain.patch import require_sha256
+
+
+_TOKEN = re.compile(r"^[a-z][a-z0-9_.-]{0,95}$")
+_PARETO_DEFINITION_DOMAIN = b"agent-evolve:objective-pareto-relation:v1\x00"
+
+
+class OutcomeRelation(str, Enum):
+    BETTER = "better"
+    WORSE = "worse"
+    EQUIVALENT = "equivalent"
+    INCOMPARABLE = "incomparable"
+
+
+OutcomeComparator = Callable[
+    [DetailedEvaluation, DetailedEvaluation],
+    OutcomeRelation,
+]
+
+
+@dataclass(frozen=True, slots=True)
+class OutcomeRelationPolicyBinding:
+    """One comparison callable and its immutable published semantics.
+
+    Archive use requires a deterministic partial order: ``BETTER``/``WORSE``
+    are inverse strict relations, ``EQUIVALENT`` is a true transitive
+    equivalence relation, and ``INCOMPARABLE`` is symmetric.  Resolution bands
+    that are not proven transitive should therefore return ``INCOMPARABLE``,
+    not ``EQUIVALENT``.  Each call verifies determinism and inverse symmetry;
+    global transitivity remains a declared policy obligation.
+    """
+
+    compare: OutcomeComparator
+    policy_id: str
+    policy_version: int
+    definition_sha256: str
+
+    def __post_init__(self) -> None:
+        if not callable(self.compare):
+            raise TypeError("compare must be callable")
+        if type(self.policy_id) is not str or _TOKEN.fullmatch(self.policy_id) is None:
+            raise ValueError("policy_id must use the closed 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")
+        require_sha256(self.definition_sha256, "definition_sha256")
+
+    @property
+    def identity(self) -> tuple[str, int, str]:
+        return self.policy_id, self.policy_version, self.definition_sha256
+
+    def relate(
+        self,
+        left: DetailedEvaluation,
+        right: DetailedEvaluation,
+    ) -> OutcomeRelation:
+        if type(left) is not DetailedEvaluation or type(right) is not DetailedEvaluation:
+            raise TypeError("outcome comparison requires exact DetailedEvaluation values")
+        DetailedEvaluation.__post_init__(left)
+        DetailedEvaluation.__post_init__(right)
+        relation = self.compare(left, right)
+        repeated = self.compare(left, right)
+        inverse = self.compare(right, left)
+        inverse_repeated = self.compare(right, left)
+        if any(
+            type(value) is not OutcomeRelation
+            for value in (relation, repeated, inverse, inverse_repeated)
+        ):
+            raise TypeError("outcome relation policy returned an invalid relation")
+        if relation is not repeated or inverse is not inverse_repeated:
+            raise ValueError("outcome relation policy must be deterministic")
+        expected_inverse = {
+            OutcomeRelation.BETTER: OutcomeRelation.WORSE,
+            OutcomeRelation.WORSE: OutcomeRelation.BETTER,
+            OutcomeRelation.EQUIVALENT: OutcomeRelation.EQUIVALENT,
+            OutcomeRelation.INCOMPARABLE: OutcomeRelation.INCOMPARABLE,
+        }[relation]
+        if inverse is not expected_inverse:
+            raise ValueError("outcome relation policy violated inverse consistency")
+        return relation
+
+    def to_record(self) -> dict[str, object]:
+        return {
+            "policy_id": self.policy_id,
+            "policy_version": self.policy_version,
+            "definition_sha256": self.definition_sha256,
+        }
+
+
+@dataclass(frozen=True, slots=True)
+class ObjectiveParetoOutcomePolicy:
+    """The legacy objective-only partial order, expressed over detailed records."""
+
+    objectives: tuple[ObjectiveSpec, ...]
+
+    def __post_init__(self) -> None:
+        if type(self.objectives) is not tuple:
+            raise TypeError("objectives must be an exact tuple")
+        validate_objective_specs(self.objectives)
+
+    @property
+    def definition_sha256(self) -> str:
+        record = [
+            {"name": objective.name, "goal": objective.goal}
+            for objective in self.objectives
+        ]
+        encoded = json.dumps(
+            record,
+            allow_nan=False,
+            ensure_ascii=True,
+            separators=(",", ":"),
+            sort_keys=True,
+        ).encode("ascii")
+        return hashlib.sha256(_PARETO_DEFINITION_DOMAIN + encoded).hexdigest()
+
+    def compare(
+        self,
+        left: DetailedEvaluation,
+        right: DetailedEvaluation,
+    ) -> OutcomeRelation:
+        if not left.success or not right.success:
+            raise ValueError("objective Pareto comparison requires successful records")
+        left_values = normalize_objective_values(
+            dict(left.objectives),
+            self.objectives,
+        )
+        right_values = normalize_objective_values(
+            dict(right.objectives),
+            self.objectives,
+        )
+        left_weak = True
+        left_strict = False
+        right_weak = True
+        right_strict = False
+        for objective in self.objectives:
+            left_value = left_values[objective.name]
+            right_value = right_values[objective.name]
+            if objective.goal == "max":
+                left_weak &= left_value >= right_value
+                left_strict |= left_value > right_value
+                right_weak &= right_value >= left_value
+                right_strict |= right_value > left_value
+            else:
+                left_weak &= left_value <= right_value
+                left_strict |= left_value < right_value
+                right_weak &= right_value <= left_value
+                right_strict |= right_value < left_value
+        if left_weak and left_strict:
+            return OutcomeRelation.BETTER
+        if right_weak and right_strict:
+            return OutcomeRelation.WORSE
+        if left_weak and right_weak:
+            return OutcomeRelation.EQUIVALENT
+        return OutcomeRelation.INCOMPARABLE
+
+    def binding(self) -> OutcomeRelationPolicyBinding:
+        return OutcomeRelationPolicyBinding(
+            compare=self.compare,
+            policy_id="objective_pareto",
+            policy_version=1,
+            definition_sha256=self.definition_sha256,
+        )
+
+
+def objective_pareto_outcome_binding(
+    objectives: Sequence[ObjectiveSpec],
+) -> OutcomeRelationPolicyBinding:
+    return ObjectiveParetoOutcomePolicy(tuple(objectives)).binding()
+
+
+__all__ = [
+    "ObjectiveParetoOutcomePolicy",
+    "OutcomeComparator",
+    "OutcomeRelation",
+    "OutcomeRelationPolicyBinding",
+    "objective_pareto_outcome_binding",
+]

agent_evolve/application/paired_allocation_comparison.py

@@ -0,0 +1,241 @@
+"""Build and replay paired v2/v3 allocation authority before outcomes."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from agent_evolve.application.action_allocation_frame_commit import (
+    validate_frame_action_allocation_phase_commit,
+)
+from agent_evolve.application.action_allocation_frame_commit_v3 import (
+    validate_operational_frame_action_allocation_phase_commit,
+)
+from agent_evolve.application.two_stage_action_evolution import (
+    TwoStageActionPhaseCommit,
+)
+from agent_evolve.domain.patch import require_sha256
+from agent_evolve.ports.action_allocation_frame import FrameActionAllocationRequest
+from agent_evolve.ports.action_allocation_frame_commit import (
+    FrameActionAllocationTreatmentExecution,
+)
+from agent_evolve.ports.action_allocation_frame_commit_v3 import (
+    OperationalFrameActionAllocationTreatmentExecution,
+)
+from agent_evolve.ports.paired_allocation_comparison import (
+    AllocationComparisonMethodKind,
+    AllocationComparisonMethodReceipt,
+    AllocationComparisonSelectedOption,
+    PairedAllocationComparisonCommitment,
+    frame_allocation_comparison_structure_sha256,
+)
+
+
+AllocationExecution = (
+    FrameActionAllocationTreatmentExecution
+    | OperationalFrameActionAllocationTreatmentExecution
+)
+
+
+@dataclass(frozen=True, slots=True)
+class AllocationComparisonMethodWave:
+    """One exact allocator method's already-durable treatment wave.
+
+    ``schedule_binding_sha256`` is a caller-verifiable receipt for the common
+    prospective schedule.  This builder binds it but does not claim that a
+    bare digest proves materialization or chronology.
+    """
+
+    comparison_method_id: str
+    schedule_binding_sha256: str
+    executions: tuple[AllocationExecution, ...] = field(
+        repr=False,
+        compare=False,
+    )
+    phase_commit: TwoStageActionPhaseCommit = field(repr=False, compare=False)
+
+    def __post_init__(self) -> None:
+        require_sha256(self.schedule_binding_sha256, "schedule_binding_sha256")
+        if type(self.executions) is not tuple or not self.executions:
+            raise ValueError("executions must be a non-empty exact tuple")
+        first_type = type(self.executions[0])
+        if first_type not in {
+            FrameActionAllocationTreatmentExecution,
+            OperationalFrameActionAllocationTreatmentExecution,
+        } or any(type(value) is not first_type for value in self.executions):
+            raise TypeError("a method wave must contain one exact execution type")
+        if type(self.phase_commit) is not TwoStageActionPhaseCommit:
+            raise TypeError("phase_commit must be exact")
+        self.phase_commit.__post_init__()
+
+
+def _base_request(execution: AllocationExecution) -> FrameActionAllocationRequest:
+    if type(execution) is FrameActionAllocationTreatmentExecution:
+        return execution.request
+    if type(execution) is OperationalFrameActionAllocationTreatmentExecution:
+        return execution.request.allocation
+    raise TypeError("execution type is outside the paired comparison")
+
+
+def _method_request_sha256(execution: AllocationExecution) -> str:
+    if type(execution) is FrameActionAllocationTreatmentExecution:
+        return execution.request.request_sha256
+    if type(execution) is OperationalFrameActionAllocationTreatmentExecution:
+        return execution.request.request_sha256
+    raise TypeError("execution type is outside the paired comparison")
+
+
+def _method_receipt(
+    wave: AllocationComparisonMethodWave,
+) -> AllocationComparisonMethodReceipt:
+    wave.__post_init__()
+    executions = wave.executions
+    if type(executions[0]) is FrameActionAllocationTreatmentExecution:
+        v2 = executions
+        assert all(
+            type(value) is FrameActionAllocationTreatmentExecution for value in v2
+        )
+        commit_input = validate_frame_action_allocation_phase_commit(
+            v2,  # type: ignore[arg-type]
+            wave.phase_commit,
+        )
+        kind = AllocationComparisonMethodKind.AUDITED_FRAME_V2
+    else:
+        v3 = executions
+        assert all(
+            type(value) is OperationalFrameActionAllocationTreatmentExecution
+            for value in v3
+        )
+        commit_input = validate_operational_frame_action_allocation_phase_commit(
+            v3,  # type: ignore[arg-type]
+            wave.phase_commit,
+        )
+        kind = AllocationComparisonMethodKind.OPERATIONAL_FRAME_V3
+
+    base_requests = tuple(_base_request(value) for value in executions)
+    expected_utility = base_requests[0].utility.utility
+    if any(value.utility.utility is not expected_utility for value in base_requests):
+        raise ValueError("one method wave must share the same utility executable")
+    structures = tuple(
+        frame_allocation_comparison_structure_sha256(value)
+        for value in base_requests
+    )
+    if len(set(structures)) != 1:
+        raise ValueError(
+            "one method wave mixes schedule/frame/eligibility/budget structure"
+        )
+    decisions = tuple(value.result.decision for value in executions)
+    allocator_identities = {
+        (
+            value.allocator_policy_id,
+            value.allocator_policy_version,
+            value.allocator_definition_sha256,
+            value.allocator_configuration_sha256,
+        )
+        for value in decisions
+    }
+    if len(allocator_identities) != 1:
+        raise ValueError("one comparison method mixes allocator configurations")
+    policy_id, policy_version, definition_sha256, configuration_sha256 = next(
+        iter(allocator_identities)
+    )
+    selected = tuple(
+        AllocationComparisonSelectedOption(
+            treatment_occurrence_id=(
+                execution.treatment_occurrence.occurrence_id.value
+            ),
+            treatment_id=execution.treatment_occurrence.treatment_id.value,
+            rank=member.rank,
+            option_id=member.option_id,
+            option_identity_sha256=member.option_identity_sha256,
+            child_configuration_sha256=member.child_configuration_sha256,
+            family=member.family,
+        )
+        for execution in executions
+        for member in execution.result.decision.members
+    )
+    assignment = executions[0].treatment_assignment
+    return AllocationComparisonMethodReceipt(
+        comparison_method_id=wave.comparison_method_id,
+        method_kind=kind,
+        schedule_binding_sha256=wave.schedule_binding_sha256,
+        allocation_phase_commit_receipt_sha256=(
+            wave.phase_commit.receipt.receipt_sha256
+        ),
+        allocation_input_sha256=commit_input.input_sha256,
+        treatment_assignment_receipt_sha256=assignment.receipt_sha256,
+        upstream_input_sha256=commit_input.upstream_input_sha256,
+        terminal_provider_ledger_commitment_sha256=(
+            commit_input.terminal_provider_ledger_commitment_sha256
+        ),
+        common_comparison_structure_sha256=structures[0],
+        allocator_policy_id=policy_id,
+        allocator_policy_version=policy_version,
+        allocator_definition_sha256=definition_sha256,
+        allocator_configuration_sha256=configuration_sha256,
+        ordered_frame_receipt_sha256s=tuple(
+            value.frame.receipt_sha256 for value in base_requests
+        ),
+        ordered_base_request_sha256s=tuple(
+            value.request_sha256 for value in base_requests
+        ),
+        ordered_method_request_sha256s=tuple(
+            _method_request_sha256(value) for value in executions
+        ),
+        ordered_decision_receipt_sha256s=tuple(
+            value.receipt_sha256 for value in decisions
+        ),
+        selected_options=selected,
+    )
+
+
+def build_paired_allocation_comparison_commitment(
+    methods: tuple[AllocationComparisonMethodWave, ...],
+) -> PairedAllocationComparisonCommitment:
+    """Validate both durable methods and bind their selected-option union."""
+
+    if type(methods) is not tuple or len(methods) != 2 or any(
+        type(value) is not AllocationComparisonMethodWave for value in methods
+    ):
+        raise ValueError("methods must contain exactly two exact method waves")
+    for value in methods:
+        value.__post_init__()
+    all_requests = tuple(
+        _base_request(execution)
+        for method in methods
+        for execution in method.executions
+    )
+    expected_utility = all_requests[0].utility.utility
+    if any(value.utility.utility is not expected_utility for value in all_requests):
+        raise ValueError("paired methods must share the same utility executable")
+    receipts = tuple(
+        sorted(
+            (_method_receipt(value) for value in methods),
+            key=lambda value: value.comparison_method_id,
+        )
+    )
+    return PairedAllocationComparisonCommitment(methods=receipts)
+
+
+def validate_paired_allocation_comparison_commitment(
+    methods: tuple[AllocationComparisonMethodWave, ...],
+    commitment: PairedAllocationComparisonCommitment,
+) -> PairedAllocationComparisonCommitment:
+    """Replay both phase commits and reject any post-commit object drift."""
+
+    if type(commitment) is not PairedAllocationComparisonCommitment:
+        raise TypeError("commitment must be exact")
+    commitment.__post_init__()
+    expected = build_paired_allocation_comparison_commitment(methods)
+    if (
+        commitment.commitment_sha256 != expected.commitment_sha256
+        or commitment.to_record() != expected.to_record()
+    ):
+        raise ValueError("paired allocation commitment differs from exact methods")
+    return expected
+
+
+__all__ = [
+    "AllocationComparisonMethodWave",
+    "build_paired_allocation_comparison_commitment",
+    "validate_paired_allocation_comparison_commitment",
+]

agent_evolve/application/paired_block_schedule.py

@@ -0,0 +1,127 @@
+"""Pure hash-ranked paired block scheduling over benchmark-neutral ports."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+import hashlib
+import json
+
+from agent_evolve.ports.paired_block_schedule import (
+    PairedBlockScheduleRequest,
+    PairedBlockSchedulePolicyBinding,
+    PairedBlockScheduleResult,
+    RankedBlockIdentity,
+)
+
+
+PAIRED_BLOCK_SCHEDULE_POLICY_ID = "paired_benchmark_block_schedule"
+PAIRED_BLOCK_SCHEDULE_POLICY_VERSION = 2
+PAIRED_BLOCK_SCHEDULE_RANK_DOMAIN = (
+    "agent-evolve:paired-benchmark-block-schedule:v2"
+)
+PAIRED_BLOCK_SCHEDULE_POLICY_DEFINITION_SHA256 = hashlib.sha256(
+    b"agent-evolve:paired-benchmark-block-schedule-policy:v2;"
+    b"inputs=benchmark,task,finite-contract,partition-layout,exact-eligible-mask,"
+    b"public-uint64-seed,public-seed-source-sha256,complete-canonical-block-"
+    b"identities,replicate-index;public-seed-source=authenticated-provenance-"
+    b"not-rank-entropy;"
+    b"rank=sha256(domain,schedule-basis,block-index,block-spec-sha256);"
+    b"sort=rank-digest-then-block-index;complete-no-replacement-schedule;"
+    b"replicate-index=exact-schedule-position;runtime-rng=forbidden;"
+    b"method,treatment,provider,prompt,outcome-identities=absent-by-construction"
+).hexdigest()
+
+
+class PairedBlockScheduleVerificationError(RuntimeError):
+    """A supplied paired schedule differs from deterministic public replay."""
+
+
+def _canonical_json(value: object) -> bytes:
+    return json.dumps(
+        value,
+        allow_nan=False,
+        ensure_ascii=True,
+        separators=(",", ":"),
+        sort_keys=True,
+    ).encode("ascii")
+
+
+def paired_block_schedule_policy() -> PairedBlockSchedulePolicyBinding:
+    """Return the identified benchmark-neutral no-replacement schedule policy."""
+
+    return PairedBlockSchedulePolicyBinding(
+        policy_id=PAIRED_BLOCK_SCHEDULE_POLICY_ID,
+        policy_version=PAIRED_BLOCK_SCHEDULE_POLICY_VERSION,
+        policy_definition_sha256=(
+            PAIRED_BLOCK_SCHEDULE_POLICY_DEFINITION_SHA256
+        ),
+        rank_domain=PAIRED_BLOCK_SCHEDULE_RANK_DOMAIN,
+    )
+
+
+def rank_paired_benchmark_blocks(
+    request: PairedBlockScheduleRequest,
+) -> PairedBlockScheduleResult:
+    """Hash-rank every block once and select the replicate's schedule position."""
+
+    if type(request) is not PairedBlockScheduleRequest:
+        raise TypeError("request must be an exact PairedBlockScheduleRequest")
+    request.__post_init__()
+    if request.policy != paired_block_schedule_policy():
+        raise ValueError("request policy differs from this identified scheduler")
+    domain = request.policy.rank_domain.encode("ascii") + b"\x00"
+    basis = request.schedule_basis_record()
+    ranked: list[tuple[str, int, object]] = []
+    for block in request.blocks:
+        rank_payload = {
+            **basis,
+            "block_index": block.block_index,
+            "block_spec_sha256": block.block_spec_sha256,
+        }
+        digest = hashlib.sha256(domain + _canonical_json(rank_payload)).hexdigest()
+        ranked.append((digest, block.block_index, block))
+    ranked.sort(key=lambda value: (value[0], value[1]))
+    return PairedBlockScheduleResult(
+        request=request,
+        ranked_blocks=tuple(
+            RankedBlockIdentity(
+                schedule_position=position,
+                block=block,  # type: ignore[arg-type]
+                rank_digest_sha256=digest,
+            )
+            for position, (digest, _block_index, block) in enumerate(ranked)
+        ),
+    )
+
+
+def verify_paired_block_schedule(
+    request: PairedBlockScheduleRequest,
+    result: PairedBlockScheduleResult | Mapping[str, object],
+) -> PairedBlockScheduleResult:
+    """Fail closed unless an object or canonical record equals public replay."""
+
+    expected = rank_paired_benchmark_blocks(request)
+    if type(result) is PairedBlockScheduleResult:
+        result.__post_init__()
+        matches = result == expected and result.to_record() == expected.to_record()
+    elif isinstance(result, Mapping):
+        matches = type(result) is dict and result == expected.to_record()
+    else:
+        raise TypeError("result must be an exact schedule result or canonical dict")
+    if not matches:
+        raise PairedBlockScheduleVerificationError(
+            "paired block schedule differs from deterministic public replay"
+        )
+    return expected
+
+
+__all__ = [
+    "PAIRED_BLOCK_SCHEDULE_POLICY_DEFINITION_SHA256",
+    "PAIRED_BLOCK_SCHEDULE_POLICY_ID",
+    "PAIRED_BLOCK_SCHEDULE_POLICY_VERSION",
+    "PAIRED_BLOCK_SCHEDULE_RANK_DOMAIN",
+    "PairedBlockScheduleVerificationError",
+    "paired_block_schedule_policy",
+    "rank_paired_benchmark_blocks",
+    "verify_paired_block_schedule",
+]