agentevolve-optimizer 0.5.0__py3-none-any.whl

agent_evolve/infrastructure/outcome_adaptive_phase_journal.py

@@ -0,0 +1,170 @@
+"""Durable JSONL interception for outcome-adaptive evolution phases."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from agent_evolve.application.outcome_adaptive_residual_portfolio_evolution import (
+    OutcomeAdaptiveResidualPhaseCommitAck,
+    OutcomeAdaptiveResidualPhaseReceipt,
+)
+from agent_evolve.domain.typed_json import freeze_json
+
+
+DURABLE_OUTCOME_ADAPTIVE_PHASE_JOURNAL_ID = (
+    "durable_jsonl_outcome_adaptive_phase_journal"
+)
+DURABLE_OUTCOME_ADAPTIVE_PHASE_JOURNAL_VERSION = 1
+DURABLE_OUTCOME_ADAPTIVE_PHASE_JOURNAL_DEFINITION_SHA256 = hashlib.sha256(
+    b"agent-evolve:durable-jsonl-outcome-adaptive-phase-journal:v1;"
+    b"record=full-receipt-evidence-plus-authenticated-ack;"
+    b"write=posix-append-before-fsync;"
+    b"first-create=parent-directory-fsync;"
+    b"duplicate-receipt=fail-closed"
+).hexdigest()
+
+
+def _canonical_json(value: object) -> bytes:
+    return json.dumps(
+        value,
+        allow_nan=False,
+        ensure_ascii=True,
+        separators=(",", ":"),
+        sort_keys=True,
+    ).encode("ascii", errors="strict")
+
+
+def _fsync_directory(path: Path) -> None:
+    if os.name != "posix":  # pragma: no cover - production target is POSIX.
+        return
+    descriptor = os.open(path, os.O_RDONLY | os.O_DIRECTORY)
+    try:
+        os.fsync(descriptor)
+    finally:
+        os.close(descriptor)
+
+
+@dataclass(slots=True)
+class DurableJsonlOutcomeAdaptivePhaseCommitter:
+    """Append and fsync every causal boundary before execution continues."""
+
+    path: Path
+    committer_id: str = field(
+        init=False,
+        default=DURABLE_OUTCOME_ADAPTIVE_PHASE_JOURNAL_ID,
+    )
+    committer_version: int = field(
+        init=False,
+        default=DURABLE_OUTCOME_ADAPTIVE_PHASE_JOURNAL_VERSION,
+    )
+    definition_sha256: str = field(
+        init=False,
+        default=DURABLE_OUTCOME_ADAPTIVE_PHASE_JOURNAL_DEFINITION_SHA256,
+    )
+    _seen_receipt_sha256s: set[str] = field(
+        init=False,
+        default_factory=set,
+    )
+    _commit_count: int = field(init=False, default=0)
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.path, Path):
+            raise TypeError("path must be a pathlib.Path")
+        if self.path.exists() and not self.path.is_file():
+            raise ValueError("phase journal path must be a regular file")
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        if not self.path.exists():
+            return
+        for line_number, raw in enumerate(
+            self.path.read_bytes().splitlines(),
+            start=1,
+        ):
+            if not raw.strip():
+                continue
+            try:
+                row = json.loads(raw)
+                receipt_sha256 = row["receipt"]["receipt_sha256"]
+                sequence = row["sequence"]
+            except (KeyError, TypeError, ValueError) as error:
+                raise ValueError(
+                    f"invalid adaptive phase journal line {line_number}"
+                ) from error
+            if (
+                type(receipt_sha256) is not str
+                or len(receipt_sha256) != 64
+                or type(sequence) is not int
+                or sequence <= 0
+            ):
+                raise ValueError(
+                    f"invalid adaptive phase journal line {line_number}"
+                )
+            if receipt_sha256 in self._seen_receipt_sha256s:
+                raise ValueError("phase journal repeats a receipt")
+            self._seen_receipt_sha256s.add(receipt_sha256)
+            self._commit_count = max(self._commit_count, sequence)
+
+    async def commit(
+        self,
+        receipt: OutcomeAdaptiveResidualPhaseReceipt,
+    ) -> OutcomeAdaptiveResidualPhaseCommitAck:
+        if type(receipt) is not OutcomeAdaptiveResidualPhaseReceipt:
+            raise TypeError("receipt must be exact")
+        receipt.__post_init__()
+        if receipt.receipt_sha256 in self._seen_receipt_sha256s:
+            raise ValueError("phase receipt was already durably committed")
+        sequence = self._commit_count + 1
+        ack = OutcomeAdaptiveResidualPhaseCommitAck(
+            committer_id=self.committer_id,
+            committer_version=self.committer_version,
+            committer_definition_sha256=self.definition_sha256,
+            phase_receipt_sha256=receipt.receipt_sha256,
+            durable=True,
+            evidence=freeze_json(
+                {
+                    "backend": "posix_append_fsync",
+                    "append_sequence": sequence,
+                    "receipt_evidence_included": True,
+                    "parent_directory_fsynced_on_create": True,
+                }
+            ),
+        )
+        row = {
+            "schema_version": 1,
+            "sequence": sequence,
+            "receipt": receipt.to_record(include_evidence=True),
+            "ack": ack.to_record(include_evidence=True),
+        }
+        payload = _canonical_json(row) + b"\n"
+        created = not self.path.exists()
+        descriptor = os.open(
+            self.path,
+            os.O_WRONLY | os.O_CREAT | os.O_APPEND,
+            0o600,
+        )
+        try:
+            offset = 0
+            while offset < len(payload):
+                written = os.write(descriptor, payload[offset:])
+                if written <= 0:  # pragma: no cover
+                    raise OSError("phase journal append made no progress")
+                offset += written
+            os.fsync(descriptor)
+        finally:
+            os.close(descriptor)
+        if created:
+            _fsync_directory(self.path.parent)
+        self._seen_receipt_sha256s.add(receipt.receipt_sha256)
+        self._commit_count = sequence
+        return ack
+
+
+__all__ = [
+    "DURABLE_OUTCOME_ADAPTIVE_PHASE_JOURNAL_DEFINITION_SHA256",
+    "DURABLE_OUTCOME_ADAPTIVE_PHASE_JOURNAL_ID",
+    "DURABLE_OUTCOME_ADAPTIVE_PHASE_JOURNAL_VERSION",
+    "DurableJsonlOutcomeAdaptivePhaseCommitter",
+]

agent_evolve/infrastructure/residual_headroom_journal.py

@@ -0,0 +1,221 @@
+"""Durable JSONL compare-and-swap store for residual-headroom closures."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from agent_evolve.application.residual_headroom_campaign_runtime import (
+    ResidualHeadroomLedgerCommitAck,
+)
+from agent_evolve.application.residual_headroom_ledger import (
+    ConservedResidualHeadroomLedger,
+    ResidualHeadroomLedgerState,
+    ResidualHeadroomStageClosure,
+)
+from agent_evolve.domain.patch import require_sha256
+from agent_evolve.domain.typed_json import freeze_json
+
+
+DURABLE_JSONL_RESIDUAL_HEADROOM_STORE_ID = (
+    "durable_jsonl_residual_headroom_store"
+)
+DURABLE_JSONL_RESIDUAL_HEADROOM_STORE_VERSION = 1
+DURABLE_JSONL_RESIDUAL_HEADROOM_STORE_DEFINITION_SHA256 = hashlib.sha256(
+    b"agent-evolve:durable-jsonl-residual-headroom-store:v1;"
+    b"compare-and-swap=expected-prior-state-sha256;"
+    b"record=full-authenticated-closure-plus-transition-ack;"
+    b"write=append-flush-fsync-before-state-publication;"
+    b"recovery=replay-and-authenticate-every-transition;"
+    b"partial-or-foreign-record=fail-closed"
+).hexdigest()
+
+
+def _canonical_json(value: object) -> str:
+    return json.dumps(
+        value,
+        allow_nan=False,
+        ensure_ascii=True,
+        separators=(",", ":"),
+        sort_keys=True,
+    )
+
+
+def _ack_from_record(
+    record: dict[str, object],
+) -> ResidualHeadroomLedgerCommitAck:
+    if type(record) is not dict:
+        raise TypeError("commit ack record must be an exact object")
+    store = record["store"]
+    if type(store) is not dict:
+        raise TypeError("commit ack store identity must be an object")
+    evidence = record.get("evidence")
+    if type(evidence) is not dict:
+        raise TypeError("durable commit ack must contain its evidence")
+    value = ResidualHeadroomLedgerCommitAck(
+        store_id=str(store["store_id"]),
+        store_version=int(store["store_version"]),
+        store_definition_sha256=str(store["definition_sha256"]),
+        prior_state_sha256=str(record["prior_state_sha256"]),
+        closure_sha256=str(record["closure_sha256"]),
+        new_state_sha256=str(record["new_state_sha256"]),
+        durable=bool(record["durable"]),
+        evidence=freeze_json(evidence),
+    )
+    if value.ack_sha256 != str(record["ack_sha256"]):
+        raise ValueError("commit ack record hash does not authenticate")
+    return value
+
+
+@dataclass(slots=True)
+class DurableJsonlResidualHeadroomStore:
+    """Append, fsync, and recover every conserved headroom transition."""
+
+    path: Path
+    ledger: ConservedResidualHeadroomLedger
+    store_id: str = DURABLE_JSONL_RESIDUAL_HEADROOM_STORE_ID
+    store_version: int = DURABLE_JSONL_RESIDUAL_HEADROOM_STORE_VERSION
+    definition_sha256: str = (
+        DURABLE_JSONL_RESIDUAL_HEADROOM_STORE_DEFINITION_SHA256
+    )
+    state: ResidualHeadroomLedgerState = field(init=False)
+    commit_acks: tuple[ResidualHeadroomLedgerCommitAck, ...] = field(
+        init=False,
+        default=(),
+    )
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.path, Path):
+            raise TypeError("path must be a pathlib.Path")
+        if type(self.ledger) is not ConservedResidualHeadroomLedger:
+            raise TypeError("ledger must be exact")
+        self.ledger.__post_init__()
+        require_sha256(self.definition_sha256, "definition_sha256")
+        if (
+            self.store_id != DURABLE_JSONL_RESIDUAL_HEADROOM_STORE_ID
+            or self.store_version
+            != DURABLE_JSONL_RESIDUAL_HEADROOM_STORE_VERSION
+            or self.definition_sha256
+            != DURABLE_JSONL_RESIDUAL_HEADROOM_STORE_DEFINITION_SHA256
+        ):
+            raise ValueError("durable store identity is immutable")
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        state = self.ledger.empty_state()
+        acknowledgements: list[ResidualHeadroomLedgerCommitAck] = []
+        if self.path.exists():
+            with self.path.open("r", encoding="utf-8") as stream:
+                for line_number, line in enumerate(stream, start=1):
+                    try:
+                        record = json.loads(line)
+                    except json.JSONDecodeError as error:
+                        raise ValueError(
+                            f"headroom journal line {line_number} is partial"
+                        ) from error
+                    if type(record) is not dict:
+                        raise TypeError(
+                            "headroom journal entries must be exact objects"
+                        )
+                    if int(record.get("schema_version", 0)) != 1:
+                        raise ValueError(
+                            "headroom journal schema is unsupported"
+                        )
+                    if (
+                        str(record["prior_state_sha256"])
+                        != state.state_sha256
+                    ):
+                        raise ValueError(
+                            "headroom journal state chain does not close"
+                        )
+                    closure_record = record["closure"]
+                    ack_record = record["commit_ack"]
+                    if (
+                        type(closure_record) is not dict
+                        or type(ack_record) is not dict
+                    ):
+                        raise TypeError(
+                            "journal closure and ack must be objects"
+                        )
+                    closure = ResidualHeadroomStageClosure.from_record(
+                        closure_record
+                    )
+                    new_state = self.ledger.append(state, closure)
+                    ack = _ack_from_record(ack_record)
+                    if (
+                        ack.store_id != self.store_id
+                        or ack.store_version != self.store_version
+                        or ack.store_definition_sha256
+                        != self.definition_sha256
+                        or ack.prior_state_sha256 != state.state_sha256
+                        or ack.closure_sha256 != closure.closure_sha256
+                        or ack.new_state_sha256
+                        != new_state.state_sha256
+                        or not ack.durable
+                        or str(record["new_state_sha256"])
+                        != new_state.state_sha256
+                    ):
+                        raise ValueError(
+                            "headroom journal transition does not authenticate"
+                        )
+                    state = new_state
+                    acknowledgements.append(ack)
+        self.state = state
+        self.commit_acks = tuple(acknowledgements)
+
+    async def commit(
+        self,
+        *,
+        expected_prior_state_sha256: str,
+        closure: ResidualHeadroomStageClosure,
+    ) -> ResidualHeadroomLedgerCommitAck:
+        require_sha256(
+            expected_prior_state_sha256,
+            "expected_prior_state_sha256",
+        )
+        if expected_prior_state_sha256 != self.state.state_sha256:
+            raise ValueError("headroom state compare-and-swap failed")
+        if type(closure) is not ResidualHeadroomStageClosure:
+            raise TypeError("closure must be exact")
+        closure.__post_init__()
+        new_state = self.ledger.append(self.state, closure)
+        ack = ResidualHeadroomLedgerCommitAck(
+            store_id=self.store_id,
+            store_version=self.store_version,
+            store_definition_sha256=self.definition_sha256,
+            prior_state_sha256=self.state.state_sha256,
+            closure_sha256=closure.closure_sha256,
+            new_state_sha256=new_state.state_sha256,
+            durable=True,
+            evidence=freeze_json(
+                {
+                    "storage": "append_only_jsonl",
+                    "flush": True,
+                    "fsync": True,
+                    "sequence": len(self.commit_acks) + 1,
+                }
+            ),
+        )
+        record = {
+            "schema_version": 1,
+            "prior_state_sha256": self.state.state_sha256,
+            "closure": closure.to_record(),
+            "new_state_sha256": new_state.state_sha256,
+            "commit_ack": ack.to_record(include_evidence=True),
+        }
+        with self.path.open("a", encoding="utf-8") as stream:
+            stream.write(_canonical_json(record) + "\n")
+            stream.flush()
+            os.fsync(stream.fileno())
+        self.state = new_state
+        self.commit_acks = (*self.commit_acks, ack)
+        return ack
+
+
+__all__ = [
+    "DURABLE_JSONL_RESIDUAL_HEADROOM_STORE_DEFINITION_SHA256",
+    "DURABLE_JSONL_RESIDUAL_HEADROOM_STORE_ID",
+    "DURABLE_JSONL_RESIDUAL_HEADROOM_STORE_VERSION",
+    "DurableJsonlResidualHeadroomStore",
+]