agentevolve-optimizer 0.5.0__py3-none-any.whl

agent_evolve/application/campaign_search_phase.py

@@ -0,0 +1,227 @@
+"""Authenticated, workload-neutral phase context for campaign acquisition.
+
+Selection policies need to know whether an evaluated slot can still create
+downstream descendants.  Without that fact a fixed exploration quota wastes
+terminal evaluations, while workload adapters are tempted to smuggle schedule
+knowledge into prompts.  This module exposes only prior schedule geometry: the
+current portfolio-generation ordinal and the number of later portfolio
+generations.  It contains no objective values, workload vocabulary, model
+identity, or outcomes.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass, field
+
+from agent_evolve.domain.typed_json import (
+    FrozenJsonObject,
+    freeze_json,
+    thaw_json,
+)
+
+
+CAMPAIGN_SEARCH_PHASE_CONTEXT_KEY = "campaign_search_phase"
+CAMPAIGN_SEARCH_PHASE_POLICY_ID = "portfolio_horizon_phase"
+CAMPAIGN_SEARCH_PHASE_POLICY_VERSION = 1
+CAMPAIGN_SEARCH_PHASE_POLICY_DEFINITION_SHA256 = hashlib.sha256(
+    b"agent-evolve:portfolio-horizon-phase:v1;"
+    b"inputs=prepared-portfolio-generation-indices,current-generation;"
+    b"outputs=ordinal,total,remaining;outcomes=false;"
+    b"workload-model-provider-fields=false"
+).hexdigest()
+_CONTEXT_DOMAIN = b"agent-evolve:campaign-search-phase-context:v1\x00"
+
+
+def _canonical_json(value: object) -> bytes:
+    return json.dumps(
+        value,
+        allow_nan=False,
+        ensure_ascii=True,
+        separators=(",", ":"),
+        sort_keys=True,
+    ).encode("ascii", errors="strict")
+
+
+@dataclass(frozen=True, slots=True)
+class CampaignSearchPhaseContext:
+    """Prior-only schedule position attached to every portfolio request."""
+
+    campaign_generation: int
+    portfolio_generation_ordinal: int
+    total_portfolio_generations: int
+    remaining_portfolio_generations: int
+    context_sha256: str = field(init=False)
+
+    def __post_init__(self) -> None:
+        for name in (
+            "campaign_generation",
+            "portfolio_generation_ordinal",
+            "total_portfolio_generations",
+            "remaining_portfolio_generations",
+        ):
+            value = getattr(self, name)
+            if type(value) is not int:
+                raise TypeError(f"{name} must be an exact integer")
+        if self.campaign_generation <= 0:
+            raise ValueError("campaign_generation must be positive")
+        if self.total_portfolio_generations <= 0:
+            raise ValueError("total_portfolio_generations must be positive")
+        if not 1 <= self.portfolio_generation_ordinal <= (
+            self.total_portfolio_generations
+        ):
+            raise ValueError("portfolio_generation_ordinal lies outside the schedule")
+        expected_remaining = (
+            self.total_portfolio_generations - self.portfolio_generation_ordinal
+        )
+        if self.remaining_portfolio_generations != expected_remaining:
+            raise ValueError("remaining portfolio horizon differs from the ordinal")
+        object.__setattr__(
+            self,
+            "context_sha256",
+            hashlib.sha256(
+                _CONTEXT_DOMAIN + _canonical_json(self._unsigned_record())
+            ).hexdigest(),
+        )
+
+    @property
+    def terminal(self) -> bool:
+        return self.remaining_portfolio_generations == 0
+
+    def _unsigned_record(self) -> dict[str, object]:
+        return {
+            "schema_version": 1,
+            "phase_policy": {
+                "policy_id": CAMPAIGN_SEARCH_PHASE_POLICY_ID,
+                "policy_version": CAMPAIGN_SEARCH_PHASE_POLICY_VERSION,
+                "definition_sha256": (
+                    CAMPAIGN_SEARCH_PHASE_POLICY_DEFINITION_SHA256
+                ),
+            },
+            "campaign_generation": self.campaign_generation,
+            "portfolio_generation_ordinal": self.portfolio_generation_ordinal,
+            "total_portfolio_generations": self.total_portfolio_generations,
+            "remaining_portfolio_generations": (
+                self.remaining_portfolio_generations
+            ),
+            "current_or_future_outcomes_consulted": False,
+        }
+
+    def to_record(self) -> dict[str, object]:
+        self.__post_init__()
+        return {**self._unsigned_record(), "context_sha256": self.context_sha256}
+
+    @classmethod
+    def from_record(cls, record: object) -> "CampaignSearchPhaseContext":
+        if type(record) is not dict or set(record) != {
+            "schema_version",
+            "phase_policy",
+            "campaign_generation",
+            "portfolio_generation_ordinal",
+            "total_portfolio_generations",
+            "remaining_portfolio_generations",
+            "current_or_future_outcomes_consulted",
+            "context_sha256",
+        }:
+            raise ValueError("campaign search phase record has an invalid field set")
+        if record["schema_version"] != 1:
+            raise ValueError("campaign search phase record has an unknown schema")
+        if record["phase_policy"] != {
+            "policy_id": CAMPAIGN_SEARCH_PHASE_POLICY_ID,
+            "policy_version": CAMPAIGN_SEARCH_PHASE_POLICY_VERSION,
+            "definition_sha256": CAMPAIGN_SEARCH_PHASE_POLICY_DEFINITION_SHA256,
+        }:
+            raise ValueError("campaign search phase policy identity differs")
+        if record["current_or_future_outcomes_consulted"] is not False:
+            raise ValueError("campaign search phase cannot consult outcomes")
+        value = cls(
+            campaign_generation=record["campaign_generation"],
+            portfolio_generation_ordinal=record["portfolio_generation_ordinal"],
+            total_portfolio_generations=record["total_portfolio_generations"],
+            remaining_portfolio_generations=record[
+                "remaining_portfolio_generations"
+            ],
+        )
+        if record["context_sha256"] != value.context_sha256:
+            raise ValueError("campaign search phase authentication failed")
+        return value
+
+
+def campaign_search_phase_context(
+    *,
+    campaign_generation: int,
+    portfolio_generations: tuple[int, ...],
+) -> CampaignSearchPhaseContext:
+    """Build the unique phase record for a prepared campaign schedule."""
+
+    if (
+        type(portfolio_generations) is not tuple
+        or not portfolio_generations
+        or any(type(value) is not int or value <= 0 for value in portfolio_generations)
+        or portfolio_generations != tuple(sorted(set(portfolio_generations)))
+    ):
+        raise ValueError("portfolio_generations must be positive and canonical")
+    try:
+        ordinal = portfolio_generations.index(campaign_generation) + 1
+    except ValueError as error:
+        raise ValueError(
+            "campaign_generation is not a portfolio generation"
+        ) from error
+    return CampaignSearchPhaseContext(
+        campaign_generation=campaign_generation,
+        portfolio_generation_ordinal=ordinal,
+        total_portfolio_generations=len(portfolio_generations),
+        remaining_portfolio_generations=len(portfolio_generations) - ordinal,
+    )
+
+
+def attach_campaign_search_phase_context(
+    context: FrozenJsonObject,
+    phase: CampaignSearchPhaseContext,
+) -> FrozenJsonObject:
+    """Append the reserved phase subtree without changing existing fields."""
+
+    if type(context) is not FrozenJsonObject or freeze_json(context) is not context:
+        raise TypeError("context must be an exact frozen object")
+    if type(phase) is not CampaignSearchPhaseContext:
+        raise TypeError("phase must be exact")
+    phase.__post_init__()
+    values = thaw_json(context)
+    if type(values) is not dict:  # pragma: no cover - frozen root is closed.
+        raise AssertionError("campaign context did not thaw to an object")
+    if CAMPAIGN_SEARCH_PHASE_CONTEXT_KEY in values:
+        raise ValueError("context already uses the reserved campaign phase key")
+    values[CAMPAIGN_SEARCH_PHASE_CONTEXT_KEY] = phase.to_record()
+    frozen = freeze_json(values)
+    if type(frozen) is not FrozenJsonObject:  # pragma: no cover - closed root.
+        raise AssertionError("campaign phase context did not freeze to an object")
+    return frozen
+
+
+def resolve_campaign_search_phase_context(
+    context: FrozenJsonObject,
+) -> CampaignSearchPhaseContext:
+    """Authenticate the phase subtree from one selection request."""
+
+    if type(context) is not FrozenJsonObject or freeze_json(context) is not context:
+        raise TypeError("context must be an exact frozen object")
+    values = thaw_json(context)
+    if type(values) is not dict:  # pragma: no cover - frozen root is closed.
+        raise AssertionError("campaign context did not thaw to an object")
+    record = values.get(CAMPAIGN_SEARCH_PHASE_CONTEXT_KEY)
+    if record is None:
+        raise ValueError("campaign context omits the reserved search phase")
+    return CampaignSearchPhaseContext.from_record(record)
+
+
+__all__ = [
+    "CAMPAIGN_SEARCH_PHASE_CONTEXT_KEY",
+    "CAMPAIGN_SEARCH_PHASE_POLICY_DEFINITION_SHA256",
+    "CAMPAIGN_SEARCH_PHASE_POLICY_ID",
+    "CAMPAIGN_SEARCH_PHASE_POLICY_VERSION",
+    "CampaignSearchPhaseContext",
+    "attach_campaign_search_phase_context",
+    "campaign_search_phase_context",
+    "resolve_campaign_search_phase_context",
+]

agent_evolve/application/campaign_selector_context_extension.py

@@ -0,0 +1,220 @@
+"""Authenticated additive context for one campaign selector request.
+
+Campaign runtimes own the complete trusted selector context.  A workload
+adapter may nevertheless need to publish a small, decision-local annotation
+that can only be computed after the runtime has selected a parent and exposed
+the current evidence cohort.  Memory transfer authority is one example.
+
+This module provides the sole generic escape hatch.  An extension is attached
+under one reserved top-level key, is source-sealed and content-addressed, and
+may only be added to an otherwise byte-identical trusted context.  It cannot
+replace or delete workload or core-authored fields.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from dataclasses import dataclass, field
+
+from agent_evolve.domain.typed_json import (
+    FrozenJsonObject,
+    freeze_json,
+    thaw_json,
+    typed_json_sha256,
+)
+
+
+CAMPAIGN_SELECTOR_CONTEXT_EXTENSION_KEY = "campaign_selector_context_extension"
+CAMPAIGN_SELECTOR_CONTEXT_EXTENSION_MAX_BYTES = 65_536
+
+_EXTENSION_DOMAIN = b"agent-evolve:campaign-selector-context-extension:v1\x00"
+_TOKEN = re.compile(r"^[a-z][a-z0-9_.-]{0,127}$")
+_LOWER_SHA256 = frozenset("0123456789abcdef")
+
+
+def _object(value: dict[str, object]) -> FrozenJsonObject:
+    frozen = freeze_json(value)
+    if type(frozen) is not FrozenJsonObject:  # pragma: no cover - closed root.
+        raise AssertionError("selector context extension did not freeze to an object")
+    return frozen
+
+
+def _canonical_bytes(value: object) -> bytes:
+    return json.dumps(
+        value,
+        allow_nan=False,
+        ensure_ascii=True,
+        separators=(",", ":"),
+        sort_keys=True,
+    ).encode("ascii", errors="strict")
+
+
+def _require_sha256(value: object, *, name: str) -> str:
+    if (
+        type(value) is not str
+        or len(value) != 64
+        or any(character not in _LOWER_SHA256 for character in value)
+    ):
+        raise ValueError(f"{name} must be a lowercase SHA-256 digest")
+    return value
+
+
+@dataclass(frozen=True, slots=True)
+class CampaignSelectorContextExtension:
+    """One source-sealed, decision-local workload annotation."""
+
+    extension_id: str
+    extension_version: int
+    definition_sha256: str
+    payload: FrozenJsonObject
+    payload_sha256: str = field(init=False)
+    extension_sha256: str = field(init=False)
+
+    def __post_init__(self) -> None:
+        if type(self.extension_id) is not str or _TOKEN.fullmatch(
+            self.extension_id
+        ) is None:
+            raise ValueError("extension_id must use the closed lowercase token grammar")
+        if type(self.extension_version) is not int or self.extension_version <= 0:
+            raise ValueError("extension_version must be a positive exact integer")
+        _require_sha256(self.definition_sha256, name="definition_sha256")
+        if (
+            type(self.payload) is not FrozenJsonObject
+            or freeze_json(self.payload) is not self.payload
+            or not self.payload.items
+        ):
+            raise TypeError("payload must be a non-empty exact frozen object")
+        payload_bytes = _canonical_bytes(thaw_json(self.payload))
+        if len(payload_bytes) > CAMPAIGN_SELECTOR_CONTEXT_EXTENSION_MAX_BYTES:
+            raise ValueError("selector context extension exceeds its byte bound")
+        payload_sha256 = typed_json_sha256(self.payload)
+        object.__setattr__(self, "payload_sha256", payload_sha256)
+        object.__setattr__(
+            self,
+            "extension_sha256",
+            hashlib.sha256(
+                _EXTENSION_DOMAIN + _canonical_bytes(self._unsigned_record())
+            ).hexdigest(),
+        )
+
+    def _unsigned_record(self) -> dict[str, object]:
+        return {
+            "schema_version": 1,
+            "extension_id": self.extension_id,
+            "extension_version": self.extension_version,
+            "definition_sha256": self.definition_sha256,
+            "payload_sha256": typed_json_sha256(self.payload),
+        }
+
+    def to_binding_record(self) -> dict[str, object]:
+        self.__post_init__()
+        return {
+            **self._unsigned_record(),
+            "extension_sha256": self.extension_sha256,
+        }
+
+    def to_prompt_record(self) -> dict[str, object]:
+        self.__post_init__()
+        return {
+            **self.to_binding_record(),
+            "payload": thaw_json(self.payload),
+        }
+
+    @classmethod
+    def from_prompt_record(
+        cls,
+        record: FrozenJsonObject,
+    ) -> "CampaignSelectorContextExtension":
+        """Replay and authenticate a model-visible extension record."""
+
+        if type(record) is not FrozenJsonObject:
+            raise TypeError("extension record must be an exact frozen object")
+        values = dict(record.items)
+        if set(values) != {
+            "schema_version",
+            "extension_id",
+            "extension_version",
+            "definition_sha256",
+            "payload_sha256",
+            "extension_sha256",
+            "payload",
+        }:
+            raise ValueError("extension record has an invalid field set")
+        if values["schema_version"] != 1:
+            raise ValueError("extension record uses an unknown schema version")
+        payload = values["payload"]
+        if type(payload) is not FrozenJsonObject:
+            raise TypeError("extension payload must remain a frozen object")
+        extension = cls(
+            extension_id=values["extension_id"],
+            extension_version=values["extension_version"],
+            definition_sha256=values["definition_sha256"],
+            payload=payload,
+        )
+        if (
+            values["payload_sha256"] != extension.payload_sha256
+            or values["extension_sha256"] != extension.extension_sha256
+        ):
+            raise ValueError("selector context extension authentication failed")
+        return extension
+
+
+def attach_campaign_selector_context_extension(
+    trusted_context: FrozenJsonObject,
+    extension: CampaignSelectorContextExtension,
+) -> FrozenJsonObject:
+    """Append one extension without changing any trusted context field."""
+
+    if type(trusted_context) is not FrozenJsonObject:
+        raise TypeError("trusted_context must be an exact frozen object")
+    if type(extension) is not CampaignSelectorContextExtension:
+        raise TypeError("extension must be exact")
+    extension.__post_init__()
+    values = thaw_json(trusted_context)
+    if type(values) is not dict:  # pragma: no cover - closed root.
+        raise AssertionError("trusted selector context did not thaw to an object")
+    if CAMPAIGN_SELECTOR_CONTEXT_EXTENSION_KEY in values:
+        raise ValueError("trusted context already uses the reserved extension key")
+    values[CAMPAIGN_SELECTOR_CONTEXT_EXTENSION_KEY] = extension.to_prompt_record()
+    return _object(values)
+
+
+def resolve_campaign_selector_context_extension(
+    *,
+    trusted_context: FrozenJsonObject,
+    selector_context: FrozenJsonObject,
+) -> CampaignSelectorContextExtension | None:
+    """Validate exact identity or one authenticated additive extension."""
+
+    if type(trusted_context) is not FrozenJsonObject:
+        raise TypeError("trusted_context must be an exact frozen object")
+    if type(selector_context) is not FrozenJsonObject:
+        raise TypeError("selector_context must be an exact frozen object")
+    trusted = dict(trusted_context.items)
+    observed = dict(selector_context.items)
+    if CAMPAIGN_SELECTOR_CONTEXT_EXTENSION_KEY in trusted:
+        raise ValueError("trusted context uses the reserved extension key")
+    if observed == trusted:
+        return None
+    if set(observed) != {
+        *trusted,
+        CAMPAIGN_SELECTOR_CONTEXT_EXTENSION_KEY,
+    }:
+        raise ValueError("selector context is not an additive extension")
+    if any(observed[key] != value for key, value in trusted.items()):
+        raise ValueError("selector context changed a trusted base field")
+    record = observed[CAMPAIGN_SELECTOR_CONTEXT_EXTENSION_KEY]
+    if type(record) is not FrozenJsonObject:
+        raise TypeError("selector context extension record must be frozen")
+    return CampaignSelectorContextExtension.from_prompt_record(record)
+
+
+__all__ = [
+    "CAMPAIGN_SELECTOR_CONTEXT_EXTENSION_KEY",
+    "CAMPAIGN_SELECTOR_CONTEXT_EXTENSION_MAX_BYTES",
+    "CampaignSelectorContextExtension",
+    "attach_campaign_selector_context_extension",
+    "resolve_campaign_selector_context_extension",
+]