agentevolve-optimizer 0.5.0__py3-none-any.whl

agent_evolve/application/artifact_journal.py

@@ -0,0 +1,246 @@
+"""Redaction-before-persistence application service for JSON artifacts."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Callable, Optional
+
+from agent_evolve.application.event_recorder import EventRecorder
+from agent_evolve.domain.artifact import ArtifactRef, ArtifactRole, artifact_ref_for_bytes
+from agent_evolve.domain.event import ArtifactRegistered, EventEnvelope
+from agent_evolve.domain.ids import CorrelationId, EventId
+from agent_evolve.ports.artifact_sanitizer import ArtifactMinimizer, ArtifactSanitizer
+from agent_evolve.ports.artifact_store import (
+    JSON_MEDIA_TYPE,
+    ArtifactStore,
+    canonical_json_bytes,
+)
+
+
+class ArtifactJournalError(RuntimeError):
+    """Base error for safe preparation or post-write verification failures."""
+
+
+class ArtifactPreparationError(ArtifactJournalError):
+    """An input could not be minimized, sanitized, and encoded safely."""
+
+
+class ArtifactSizeLimitError(ArtifactPreparationError):
+    """The sanitized canonical representation exceeds the configured limit."""
+
+
+class ArtifactPostWriteVerificationError(ArtifactJournalError):
+    """The durable store did not reproduce the complete expected reference."""
+
+
+AfterArtifactPutHook = Callable[[ArtifactRef], None]
+_PREPARATION_FAILED = object()
+
+
+@dataclass(frozen=True, slots=True)
+class ArtifactRegistrationResult:
+    """Successful durable registration returned by :class:`ArtifactJournal`."""
+
+    artifact_ref: ArtifactRef
+    event: EventEnvelope
+
+
+class ArtifactJournal:
+    """Prepare, durably store, verify, and then journal a canonical JSON value.
+
+    Raw caller input is passed only to the in-memory minimizer and sanitizer.
+    The sole artifact-store call that writes bytes receives the already
+    sanitized canonical encoding.
+    """
+
+    def __init__(
+        self,
+        *,
+        artifact_store: ArtifactStore,
+        event_recorder: EventRecorder,
+        minimizer: ArtifactMinimizer,
+        sanitizer: ArtifactSanitizer,
+        max_size_bytes: int,
+        after_artifact_put: AfterArtifactPutHook | None = None,
+    ) -> None:
+        if (
+            isinstance(max_size_bytes, bool)
+            or not isinstance(max_size_bytes, int)
+            or max_size_bytes < 1
+        ):
+            raise ValueError("max_size_bytes must be a positive integer")
+        self._artifact_store = artifact_store
+        self._event_recorder = event_recorder
+        self._minimizer = minimizer
+        self._sanitizer = sanitizer
+        self._max_size_bytes = max_size_bytes
+        self._after_artifact_put = after_artifact_put
+
+    @staticmethod
+    def _preparation_failure() -> ArtifactPreparationError:
+        # This message intentionally contains no value, field path, match count,
+        # or chained exception from a caller-supplied policy implementation.
+        return ArtifactPreparationError(
+            "artifact preparation failed under the configured safety policies"
+        )
+
+    def _minimize_without_leaky_context(self, value: Any, role: ArtifactRole) -> Any:
+        try:
+            return (
+                self._minimizer.minimize_json(value, role=role),
+                self._minimizer.policy_id,
+                self._minimizer.policy_version,
+                self._minimizer.policy_config_sha256,
+            )
+        except Exception:
+            # Returning from the handler clears Python's implicit exception
+            # context before the caller constructs the public safe error.
+            return _PREPARATION_FAILED
+
+    def _sanitize_without_leaky_context(
+        self,
+        value: Any,
+        role: ArtifactRole,
+    ) -> Any:
+        try:
+            sanitized = self._sanitizer.sanitize_json(value, role=role)
+            return (
+                sanitized,
+                self._sanitizer.policy_id,
+                self._sanitizer.policy_version,
+            )
+        except Exception:
+            return _PREPARATION_FAILED
+
+    @staticmethod
+    def _encode_without_leaky_context(value: Any) -> bytes | object:
+        try:
+            return canonical_json_bytes(value)
+        except Exception:
+            return _PREPARATION_FAILED
+
+    @staticmethod
+    def _registration_without_leaky_context(
+        expected_ref: ArtifactRef,
+        role: ArtifactRole,
+        minimization_policy_id: Any,
+        minimization_policy_version: Any,
+        minimization_policy_config_sha256: Any,
+        policy_id: Any,
+        policy_version: Any,
+    ) -> ArtifactRegistered | object:
+        try:
+            return ArtifactRegistered(
+                artifact_id=expected_ref.artifact_id,
+                sha256_hex=expected_ref.sha256_hex,
+                size_bytes=expected_ref.size_bytes,
+                media_type=expected_ref.media_type,
+                role=role,
+                minimization_policy_id=minimization_policy_id,
+                minimization_policy_version=minimization_policy_version,
+                minimization_policy_config_sha256=(
+                    minimization_policy_config_sha256
+                ),
+                sanitization_policy_id=policy_id,
+                sanitization_policy_version=policy_version,
+            )
+        except Exception:
+            return _PREPARATION_FAILED
+
+    def register_json(
+        self,
+        value: Any,
+        *,
+        role: ArtifactRole,
+        correlation_id: Optional[CorrelationId] = None,
+        causation_event_id: Optional[EventId] = None,
+    ) -> ArtifactRegistrationResult:
+        """Register one minimized and sanitized JSON artifact.
+
+        Ordering is a safety and crash-consistency contract, not an
+        implementation detail: minimize -> sanitize -> canonical encode -> size
+        gate -> durable put -> full verification -> durable event append.
+        """
+
+        if not isinstance(role, ArtifactRole):
+            raise TypeError("role must be an ArtifactRole")
+
+        minimization_result = self._minimize_without_leaky_context(value, role)
+        if minimization_result is _PREPARATION_FAILED:
+            raise self._preparation_failure()
+        (
+            minimized,
+            minimization_policy_id,
+            minimization_policy_version,
+            minimization_policy_config_sha256,
+        ) = minimization_result
+        sanitized_result = self._sanitize_without_leaky_context(minimized, role)
+        if sanitized_result is _PREPARATION_FAILED:
+            raise self._preparation_failure()
+        sanitized, policy_id, policy_version = sanitized_result
+        encoded = self._encode_without_leaky_context(sanitized)
+        if encoded is _PREPARATION_FAILED:
+            raise self._preparation_failure()
+        assert isinstance(encoded, bytes)  # narrowed from the private sentinel union
+
+        if len(encoded) > self._max_size_bytes:
+            raise ArtifactSizeLimitError(
+                "sanitized artifact exceeds the configured size limit"
+            )
+
+        expected_ref = artifact_ref_for_bytes(encoded, media_type=JSON_MEDIA_TYPE)
+        # Constructing the payload before the write validates all provenance
+        # metadata.  It is appended only after post-write verification succeeds.
+        registration = self._registration_without_leaky_context(
+            expected_ref,
+            role,
+            minimization_policy_id,
+            minimization_policy_version,
+            minimization_policy_config_sha256,
+            policy_id,
+            policy_version,
+        )
+        if registration is _PREPARATION_FAILED:
+            raise self._preparation_failure()
+        assert isinstance(registration, ArtifactRegistered)
+
+        persisted_ref = self._artifact_store.put_bytes(
+            encoded,
+            media_type=JSON_MEDIA_TYPE,
+        )
+        if self._after_artifact_put is not None:
+            # A test/deployment crash hook receives only content metadata, never
+            # the raw or sanitized payload.  Raising leaves a store-only orphan.
+            self._after_artifact_put(expected_ref)
+
+        try:
+            stat_ref = self._artifact_store.stat(expected_ref.artifact_id)
+            reread = self._artifact_store.read_bytes(
+                expected_ref.artifact_id,
+                expected_media_type=JSON_MEDIA_TYPE,
+            )
+            reread_ref = artifact_ref_for_bytes(
+                reread,
+                media_type=JSON_MEDIA_TYPE,
+            )
+        except Exception:
+            raise ArtifactPostWriteVerificationError(
+                "artifact could not be fully verified after persistence"
+            ) from None
+
+        if (
+            persisted_ref != expected_ref
+            or stat_ref != expected_ref
+            or reread_ref != expected_ref
+            or reread != encoded
+        ):
+            raise ArtifactPostWriteVerificationError(
+                "artifact metadata or bytes changed during persistence"
+            )
+
+        event = self._event_recorder.record(
+            registration,
+            correlation_id=correlation_id,
+            causation_event_id=causation_event_id,
+        )
+        return ArtifactRegistrationResult(artifact_ref=expected_ref, event=event)

agent_evolve/application/artifact_replay.py

@@ -0,0 +1,347 @@
+"""Read-only replay and integrity verification for artifact registrations."""
+
+from __future__ import annotations
+
+import types
+from dataclasses import dataclass, fields
+from typing import Any, Iterable, Optional, Tuple, Union, get_args, get_origin, get_type_hints
+
+from agent_evolve.domain.artifact import ArtifactRef, ArtifactRole, artifact_ref_for_bytes
+from agent_evolve.domain.event import (
+    EVENT_PAYLOAD_TYPES,
+    ArtifactRegistered,
+    CandidateProposed,
+    EvaluationFailed,
+    EventEnvelope,
+    EventPayload,
+    LLMCallCompleted,
+    LLMCallFailed,
+    LLMRequestArtifactLinked,
+    ProviderAttemptFailed,
+    RunAborted,
+    RunStarted,
+    validated_event_snapshot,
+)
+from agent_evolve.domain.ids import ArtifactId, RunId
+from agent_evolve.ports.artifact_store import (
+    JSON_MEDIA_TYPE,
+    ArtifactStore,
+    canonical_json_bytes,
+    decode_json_bytes,
+)
+
+
+class ArtifactReplayError(RuntimeError):
+    """The event stream and artifact store do not form a valid journal."""
+
+
+class ArtifactStreamOrderError(ArtifactReplayError):
+    """Replay input is not one contiguous run stream in sequence order."""
+
+
+class ArtifactRegistrationIntegrityError(ArtifactReplayError):
+    """A registration claim is inconsistent with the durable store."""
+
+
+class DanglingArtifactReferenceError(ArtifactReplayError):
+    """A semantic reference has no preceding registration."""
+
+
+class IncompatibleArtifactRoleError(ArtifactReplayError):
+    """An artifact was registered earlier, but not under the required role."""
+
+
+class ArtifactReferenceSchemaError(ArtifactReplayError):
+    """An ArtifactId-bearing payload field has no explicit role rule."""
+
+
+_SNAPSHOT_FAILED = object()
+_REGISTRATION_VERIFICATION_FAILED = object()
+_REGISTRATION_MISMATCH = object()
+
+
+@dataclass(frozen=True, slots=True)
+class ArtifactRegistrationKey:
+    artifact_id: ArtifactId
+    role: ArtifactRole
+
+
+@dataclass(frozen=True, slots=True)
+class ArtifactReplayReport:
+    run_id: Optional[RunId]
+    event_count: int
+    registration_event_count: int
+    semantic_reference_count: int
+    unique_registration_count: int
+    unique_referenced_registration_count: int
+    orphan_registrations: Tuple[ArtifactRegistrationKey, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class _RegistrationClaim:
+    artifact_ref: ArtifactRef
+    minimization_policy_id: str
+    minimization_policy_version: str
+    minimization_policy_config_sha256: str
+    policy_id: str
+    policy_version: str
+
+
+# The map is intentionally explicit and fail-closed.  Adding an ArtifactId field
+# to the event vocabulary requires declaring which semantic role may satisfy it.
+_REFERENCE_ROLES: dict[type[EventPayload], dict[str, ArtifactRole]] = {
+    RunStarted: {"manifest_artifact_id": ArtifactRole.RUN_MANIFEST},
+    RunAborted: {"diagnostics_artifact_id": ArtifactRole.DIAGNOSTICS},
+    LLMCallCompleted: {"response_artifact_id": ArtifactRole.LLM_RESPONSE},
+    LLMRequestArtifactLinked: {"request_artifact_id": ArtifactRole.LLM_REQUEST},
+    LLMCallFailed: {"diagnostics_artifact_id": ArtifactRole.DIAGNOSTICS},
+    ProviderAttemptFailed: {"diagnostics_artifact_id": ArtifactRole.DIAGNOSTICS},
+    CandidateProposed: {
+        "configuration_artifact_id": ArtifactRole.CANDIDATE_CONFIGURATION
+    },
+    EvaluationFailed: {"diagnostics_artifact_id": ArtifactRole.DIAGNOSTICS},
+}
+
+
+def _annotation_contains_artifact_id(annotation: Any) -> bool:
+    if annotation is ArtifactId:
+        return True
+    origin = get_origin(annotation)
+    if origin in (Union, types.UnionType) or origin in (tuple, list, dict):
+        return any(_annotation_contains_artifact_id(arg) for arg in get_args(annotation))
+    return False
+
+
+def _annotation_is_scalar_artifact_id(annotation: Any) -> bool:
+    if annotation is ArtifactId:
+        return True
+    origin = get_origin(annotation)
+    args = get_args(annotation)
+    return origin in (Union, types.UnionType) and set(args) == {
+        ArtifactId,
+        type(None),
+    }
+
+
+def _artifact_fields(payload: EventPayload) -> tuple[str, ...]:
+    hints = get_type_hints(type(payload))
+    return tuple(
+        field.name
+        for field in fields(payload)
+        if _annotation_contains_artifact_id(hints[field.name])
+    )
+
+
+def validate_artifact_reference_schema() -> None:
+    """Fail if the complete event vocabulary and semantic role map drift apart."""
+
+    payload_types = set(EVENT_PAYLOAD_TYPES)
+    extra_rule_types = set(_REFERENCE_ROLES) - payload_types
+    if extra_rule_types:
+        raise ArtifactReferenceSchemaError(
+            "artifact reference role rules include an unregistered event payload"
+        )
+
+    for payload_type in EVENT_PAYLOAD_TYPES:
+        if payload_type is ArtifactRegistered:
+            hints = get_type_hints(payload_type)
+            registration_artifact_fields = {
+                field.name
+                for field in fields(payload_type)
+                if _annotation_contains_artifact_id(hints[field.name])
+            }
+            if registration_artifact_fields != {"artifact_id"}:
+                raise ArtifactReferenceSchemaError(
+                    "ArtifactRegistered identity fields require an explicit schema review"
+                )
+            continue
+        hints = get_type_hints(payload_type)
+        artifact_fields = {
+            field.name
+            for field in fields(payload_type)
+            if _annotation_contains_artifact_id(hints[field.name])
+        }
+        declared_roles = _REFERENCE_ROLES.get(payload_type, {})
+        if artifact_fields != set(declared_roles):
+            raise ArtifactReferenceSchemaError(
+                "artifact reference role rules do not match the event schema"
+            )
+        for field_name in artifact_fields:
+            if not _annotation_is_scalar_artifact_id(hints[field_name]):
+                raise ArtifactReferenceSchemaError(
+                    "non-scalar ArtifactId references require an explicit replay design"
+                )
+            if not isinstance(declared_roles[field_name], ArtifactRole):
+                raise ArtifactReferenceSchemaError(
+                    "artifact reference rules must declare a constrained role"
+                )
+
+
+# Validate the whole vocabulary at import, not only payload types encountered by
+# a particular run.  A schema change therefore cannot remain latent in quiet runs.
+validate_artifact_reference_schema()
+
+
+def _try_verify_registration_store(
+    registration: ArtifactRegistered,
+    store: ArtifactStore,
+) -> ArtifactRef | object:
+    expected = registration.artifact_ref
+    try:
+        stat_ref = store.stat(expected.artifact_id)
+        content = store.read_bytes(
+            expected.artifact_id,
+            expected_media_type=expected.media_type,
+        )
+        content_ref = artifact_ref_for_bytes(content, media_type=expected.media_type)
+        decoded = decode_json_bytes(content)
+        canonical_content = canonical_json_bytes(decoded)
+        if (
+            stat_ref != expected
+            or content_ref != expected
+            or canonical_content != content
+        ):
+            return _REGISTRATION_MISMATCH
+    except Exception:
+        # Return from the handler so secret-bearing adapter/codec exceptions do
+        # not become context on the public integrity error raised by the caller.
+        return _REGISTRATION_VERIFICATION_FAILED
+    return expected
+
+
+def _verify_registration_store(
+    registration: ArtifactRegistered,
+    store: ArtifactStore,
+) -> ArtifactRef:
+    expected = registration.artifact_ref
+    if expected.media_type != JSON_MEDIA_TYPE:
+        raise ArtifactRegistrationIntegrityError(
+            "M1c registrations must use the canonical JSON media type"
+        )
+    verification = _try_verify_registration_store(registration, store)
+    if verification is _REGISTRATION_VERIFICATION_FAILED:
+        raise ArtifactRegistrationIntegrityError(
+            "a registered artifact could not be verified in the durable store"
+        )
+    if verification is _REGISTRATION_MISMATCH:
+        raise ArtifactRegistrationIntegrityError(
+            "a registration does not match a canonical durable artifact reference"
+        )
+    assert type(verification) is ArtifactRef
+    return verification
+
+
+def verify_artifact_journal(
+    events: Iterable[EventEnvelope],
+    *,
+    artifact_store: ArtifactStore,
+) -> ArtifactReplayReport:
+    """Verify one run deterministically without mutating events or artifacts.
+
+    Registrations that are never referenced are valid: they can result from a
+    crash after registration but before the semantic event.  Conversely, a
+    store-only orphan has no journal record and is deliberately invisible here.
+    """
+
+    try:
+        stream = tuple(validated_event_snapshot(event) for event in events)
+    except Exception:
+        stream = _SNAPSHOT_FAILED
+    if stream is _SNAPSHOT_FAILED:
+        raise ArtifactStreamOrderError(
+            "artifact replay requires canonically validated event snapshots"
+        )
+    assert isinstance(stream, tuple)
+
+    run_id: Optional[RunId] = None
+    expected_sequence = 1
+    event_count = 0
+    registration_event_count = 0
+    semantic_reference_count = 0
+    registrations: dict[ArtifactRegistrationKey, _RegistrationClaim] = {}
+    refs_by_id: dict[ArtifactId, ArtifactRef] = {}
+    roles_by_id: dict[ArtifactId, set[ArtifactRole]] = {}
+    referenced: set[ArtifactRegistrationKey] = set()
+
+    for event in stream:
+        event_count += 1
+        if run_id is None:
+            run_id = event.run_id
+        elif event.run_id != run_id:
+            raise ArtifactStreamOrderError(
+                "artifact replay requires events from exactly one run"
+            )
+        if event.sequence_number != expected_sequence:
+            raise ArtifactStreamOrderError(
+                "artifact replay requires a contiguous sequence beginning at one"
+            )
+        expected_sequence += 1
+
+        payload = event.payload
+        if isinstance(payload, ArtifactRegistered):
+            registration_event_count += 1
+            ref = _verify_registration_store(payload, artifact_store)
+            previous_ref = refs_by_id.get(ref.artifact_id)
+            if previous_ref is not None and previous_ref != ref:
+                raise ArtifactRegistrationIntegrityError(
+                    "registrations disagree on a complete artifact reference"
+                )
+            refs_by_id[ref.artifact_id] = ref
+            key = ArtifactRegistrationKey(ref.artifact_id, payload.role)
+            claim = _RegistrationClaim(
+                artifact_ref=ref,
+                minimization_policy_id=payload.minimization_policy_id,
+                minimization_policy_version=payload.minimization_policy_version,
+                minimization_policy_config_sha256=(
+                    payload.minimization_policy_config_sha256
+                ),
+                policy_id=payload.sanitization_policy_id,
+                policy_version=payload.sanitization_policy_version,
+            )
+            previous_claim = registrations.get(key)
+            if previous_claim is not None and previous_claim != claim:
+                raise ArtifactRegistrationIntegrityError(
+                    "duplicate registrations disagree on provenance"
+                )
+            registrations[key] = claim
+            roles_by_id.setdefault(ref.artifact_id, set()).add(payload.role)
+            continue
+
+        artifact_fields = _artifact_fields(payload)
+        declared_roles = _REFERENCE_ROLES.get(type(payload), {})
+        if set(artifact_fields) != set(declared_roles):
+            raise ArtifactReferenceSchemaError(
+                "artifact reference role rules do not match the event schema"
+            )
+        for field_name in artifact_fields:
+            artifact_id = getattr(payload, field_name)
+            if artifact_id is None:
+                continue
+            semantic_reference_count += 1
+            role = declared_roles[field_name]
+            key = ArtifactRegistrationKey(artifact_id, role)
+            if key not in registrations:
+                if artifact_id in roles_by_id:
+                    raise IncompatibleArtifactRoleError(
+                        "an artifact reference has no preceding compatible role"
+                    )
+                raise DanglingArtifactReferenceError(
+                    "an artifact reference has no preceding registration"
+                )
+            referenced.add(key)
+
+    orphan_keys = tuple(
+        sorted(
+            set(registrations) - referenced,
+            key=lambda key: (key.artifact_id.value, key.role.value),
+        )
+    )
+    return ArtifactReplayReport(
+        run_id=run_id,
+        event_count=event_count,
+        registration_event_count=registration_event_count,
+        semantic_reference_count=semantic_reference_count,
+        unique_registration_count=len(registrations),
+        unique_referenced_registration_count=len(referenced),
+        orphan_registrations=orphan_keys,
+    )