apsimo 1.3.0__py3-none-any.whl

apsimo/task_queue/action_receipts.py

@@ -0,0 +1,148 @@
+"""Strict, digest-bound receipt attestation for generic Action Plane work."""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from datetime import datetime, timezone
+import hashlib
+import json
+import re
+from typing import Any, Mapping, Tuple
+
+from apsimo.execution_results import bounded_refs
+
+
+ACTION_RECEIPT_SCHEMA = "ActionReceiptAttestationV1"
+ACTION_RECEIPT_VERSION = 1
+ACTION_EFFECT_CLASSES = frozenset({"mutation", "disclosure"})
+_SHA256_RE = re.compile(r"^[0-9a-f]{64}$")
+_FIELDS = frozenset({
+    "schema", "version", "job_id", "action_digest", "claim_attempt_id",
+    "effect_class", "terminal_outcome", "receipt_refs", "observed_at",
+    "summary",
+})
+
+
+class ActionReceiptError(ValueError):
+    """The verifier supplied a malformed or unbound attestation."""
+
+
+def _bounded(value: object, field: str, maximum: int, *, required=True) -> str:
+    text = str(value or "").strip()
+    if (required and not text) or len(text) > maximum:
+        qualifier = f"1..{maximum}" if required else f"0..{maximum}"
+        raise ActionReceiptError(f"{field} must be {qualifier} characters")
+    return text
+
+
+@dataclass(frozen=True)
+class ActionReceiptAttestationV1:
+    """One verifier assertion bound to an exact action and claim attempt."""
+
+    job_id: str
+    action_digest: str
+    claim_attempt_id: str
+    effect_class: str
+    terminal_outcome: str
+    receipt_refs: Tuple[str, ...]
+    observed_at: str
+    summary: str = ""
+    schema: str = ACTION_RECEIPT_SCHEMA
+    version: int = ACTION_RECEIPT_VERSION
+
+    @classmethod
+    def from_payload(cls, value: object) -> "ActionReceiptAttestationV1":
+        if not isinstance(value, Mapping):
+            raise ActionReceiptError("action receipt must be an object")
+        raw = dict(value)
+        unknown = set(raw) - _FIELDS
+        missing = _FIELDS - set(raw)
+        if unknown or missing:
+            raise ActionReceiptError(
+                "action receipt fields do not match V1 contract"
+            )
+        if raw.get("schema") != ACTION_RECEIPT_SCHEMA:
+            raise ActionReceiptError("action receipt schema is unsupported")
+        if (
+            type(raw.get("version")) is not int
+            or raw["version"] != ACTION_RECEIPT_VERSION
+        ):
+            raise ActionReceiptError("action receipt version is unsupported")
+        for field in (
+            "job_id", "action_digest", "claim_attempt_id", "effect_class",
+            "terminal_outcome", "observed_at", "summary",
+        ):
+            if type(raw.get(field)) is not str:
+                raise ActionReceiptError(
+                    f"action receipt {field} must be a string"
+                )
+        digest = str(raw.get("action_digest") or "").strip().lower()
+        if not _SHA256_RE.fullmatch(digest) or set(digest) == {"0"}:
+            raise ActionReceiptError(
+                "action_digest must be a non-null lowercase SHA-256"
+            )
+        effect_class = str(raw.get("effect_class") or "").strip().lower()
+        if effect_class not in ACTION_EFFECT_CLASSES:
+            raise ActionReceiptError(
+                "effect_class must be mutation or disclosure"
+            )
+        if raw.get("terminal_outcome") != "succeeded":
+            raise ActionReceiptError(
+                "success attestation terminal_outcome must be succeeded"
+            )
+        try:
+            observed = datetime.fromisoformat(
+                str(raw.get("observed_at") or "").replace("Z", "+00:00")
+            )
+        except ValueError as exc:
+            raise ActionReceiptError(
+                "observed_at must be an ISO-8601 timestamp"
+            ) from exc
+        if observed.tzinfo is None:
+            raise ActionReceiptError("observed_at must include a timezone")
+        refs = bounded_refs(raw.get("receipt_refs"))
+        if not refs:
+            raise ActionReceiptError(
+                "verified action effect requires a receipt reference"
+            )
+        return cls(
+            job_id=_bounded(raw.get("job_id"), "job_id", 128),
+            action_digest=digest,
+            claim_attempt_id=_bounded(
+                raw.get("claim_attempt_id"), "claim_attempt_id", 128,
+            ),
+            effect_class=effect_class,
+            terminal_outcome="succeeded",
+            receipt_refs=refs,
+            observed_at=observed.astimezone(timezone.utc).isoformat(),
+            summary=_bounded(
+                raw.get("summary"), "summary", 500, required=False,
+            ),
+        )
+
+    def payload(self) -> dict[str, Any]:
+        payload = asdict(self)
+        payload["receipt_refs"] = list(self.receipt_refs)
+        return payload
+
+    def evidence_sha256(
+        self,
+        *,
+        verifier_identity: str,
+        verifier_type: str,
+    ) -> str:
+        """Digest the canonical assertion plus server-derived authority."""
+
+        document = {
+            **self.payload(),
+            "verifier_identity": _bounded(
+                verifier_identity, "verifier_identity", 256,
+            ),
+            "verifier_type": _bounded(verifier_type, "verifier_type", 128),
+        }
+        return hashlib.sha256(json.dumps(
+            document,
+            sort_keys=True,
+            separators=(",", ":"),
+            ensure_ascii=True,
+        ).encode("utf-8")).hexdigest()

apsimo/task_queue/approval_relay_canary.py

@@ -0,0 +1,108 @@
+"""Server-owned, permanently inert approval-relay calibration job.
+
+The canary exists only to prove Colony -> host owner transport -> Colony
+decision relay before generic effects are enabled.  It deliberately uses the
+normal canonical approval ledger while having no executable terminal path.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import re
+from typing import Any, Mapping
+
+from apsimo.task_queue.models import Job, JobPriority, JobStatus, JobType
+
+
+SCHEMA = "ApprovalRelayCanaryV1"
+VERSION = 1
+ACTION_HINT = "approval_relay_canary"
+JOB_ID_PREFIX = "approval-relay-canary:"
+POSTED_BY = "colony:approval-relay-canary"
+TERMINAL_POLICY = "record_decision_then_cancel_without_execution"
+APPROVAL_TTL_SECONDS = 60 * 60
+_SHA256 = re.compile(r"^[0-9a-f]{64}$")
+
+
+def idempotency_digest(value: str) -> str:
+    """Hash one bounded opaque token so caller material is never persisted."""
+
+    if not isinstance(value, str) or value != value.strip():
+        raise ValueError("approval relay canary idempotency key is invalid")
+    if not 16 <= len(value) <= 128 or any(character.isspace() for character in value):
+        raise ValueError("approval relay canary idempotency key is invalid")
+    return hashlib.sha256(value.encode("utf-8")).hexdigest()
+
+
+def job_id_for_digest(digest: str) -> str:
+    if not isinstance(digest, str) or not _SHA256.fullmatch(digest):
+        raise ValueError("approval relay canary idempotency digest is invalid")
+    return JOB_ID_PREFIX + digest
+
+
+def payload_for_digest(digest: str) -> dict[str, Any]:
+    job_id_for_digest(digest)
+    return {
+        "schema": SCHEMA,
+        "version": VERSION,
+        "action_hint": ACTION_HINT,
+        "risk": "mutating",
+        "description": (
+            "Approval relay calibration only. No tool, worker, external "
+            "write, or outbound action will run for either decision."
+        ),
+        "external_effect": False,
+        "reversible": True,
+        "terminal_policy": TERMINAL_POLICY,
+        "idempotency_digest": digest,
+    }
+
+
+def build_job(digest: str) -> Job:
+    """Build the only queue object accepted as this reserved canary."""
+
+    return Job(
+        job_id=job_id_for_digest(digest),
+        job_type=JobType.AGENT_ACTION,
+        payload=payload_for_digest(digest),
+        priority=JobPriority.NORMAL,
+        max_retries=0,
+        timeout_secs=60.0,
+        posted_by=POSTED_BY,
+        status=JobStatus.BLOCKED,
+        tags={
+            "hold_kind": "approval",
+            "blocked_reason": "awaiting_owner_approval",
+            "awaiting_owner_approval": "true",
+            "approval_relay_canary": "true",
+            "external_effect": "false",
+            "terminal_policy": TERMINAL_POLICY,
+        },
+    )
+
+
+def is_exact_job(job: Job) -> bool:
+    """Recognize only the complete server-derived object, never loose tags."""
+
+    payload: Mapping[str, Any] = job.payload if isinstance(job.payload, Mapping) else {}
+    digest = payload.get("idempotency_digest")
+    if not isinstance(digest, str) or not _SHA256.fullmatch(digest):
+        return False
+    expected_payload = payload_for_digest(digest)
+    return bool(
+        job.job_type is JobType.AGENT_ACTION
+        and hmac.compare_digest(job.job_id, job_id_for_digest(digest))
+        and job.posted_by == POSTED_BY
+        and job.max_retries == 0
+        and float(job.timeout_secs) == 60.0
+        and dict(payload) == expected_payload
+        and job.tags.get("approval_relay_canary") == "true"
+        and job.tags.get("external_effect") == "false"
+        and job.tags.get("terminal_policy") == TERMINAL_POLICY
+    )
+
+
+def assert_exact_job(job: Job) -> None:
+    if not is_exact_job(job):
+        raise ValueError("approval relay canary identity or inert contract drifted")

apsimo/task_queue/config.py

@@ -0,0 +1,85 @@
+"""Configuration for the Colony distributed task queue."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+import math
+from pathlib import Path
+
+
+DEFAULT_WORKER_HEARTBEAT_TTL_SECS = 60.0
+MIN_WORKER_HEARTBEAT_TTL_SECS = 1.0
+MAX_WORKER_HEARTBEAT_TTL_SECS = 3600.0
+
+
+def validate_worker_heartbeat_ttl(value: object) -> float:
+    """Return the one bounded worker-liveness TTL used by queue consumers."""
+
+    try:
+        parsed = float(value)
+    except (TypeError, ValueError) as exc:
+        raise ValueError(
+            "worker_heartbeat_ttl_secs must be between "
+            f"{MIN_WORKER_HEARTBEAT_TTL_SECS:g} and "
+            f"{MAX_WORKER_HEARTBEAT_TTL_SECS:g}"
+        ) from exc
+    if (
+        not math.isfinite(parsed)
+        or parsed < MIN_WORKER_HEARTBEAT_TTL_SECS
+        or parsed > MAX_WORKER_HEARTBEAT_TTL_SECS
+    ):
+        raise ValueError(
+            "worker_heartbeat_ttl_secs must be between "
+            f"{MIN_WORKER_HEARTBEAT_TTL_SECS:g} and "
+            f"{MAX_WORKER_HEARTBEAT_TTL_SECS:g}"
+        )
+    return parsed
+
+
+@dataclass
+class TaskQueueConfig:
+    """Configuration for the distributed task queue.
+
+    All timeouts are in seconds unless otherwise stated.
+    """
+
+    # Storage
+    db_path: Path = field(default_factory=lambda: Path("~/.colony/task_queue.db"))
+
+    # Scheduling
+    scheduler_tick_secs: float = 2.0
+    """How often the scheduler runs its assignment loop."""
+
+    # Worker health
+    heartbeat_interval_secs: float = 15.0
+    """How often workers send heartbeats."""
+
+    heartbeat_timeout_secs: float = DEFAULT_WORKER_HEARTBEAT_TTL_SECS
+    """Time after which a silent worker's jobs are abandoned."""
+
+    claim_timeout_secs: float = 30.0
+    """Time after which a CLAIMED but not yet RUNNING job is re-queued."""
+
+    # Deadlines
+    no_worker_warning_secs: float = 300.0
+    """Emit warning when a job with a deadline within this window has no eligible worker."""
+
+    # Retries
+    default_max_retries: int = 3
+    """Default retry limit for jobs that do not specify one."""
+
+    # History retention
+    completed_job_retention_days: int = 30
+    failed_job_retention_days: int = 7
+
+    # Capacity
+    default_worker_max_concurrent: int = 4
+    """Default maximum concurrent jobs per worker if not specified."""
+
+    # Regent sync
+    regent_sync_interval_secs: float = 5.0
+    """How often the Regent syncs queue state from the Sovereign."""
+
+    def resolved_db_path(self) -> Path:
+        """Return the db_path with ~ expanded."""
+        return Path(self.db_path).expanduser()