actenon-kernel 0.1.0__py3-none-any.whl

actenon/anchors/__init__.py

@@ -0,0 +1,29 @@
+"""Local external anchor primitives for receipt/refusal durability."""
+
+from .local_log import LocalAppendOnlyAnchorLog
+from .models import (
+    EXTERNAL_ANCHOR_CONTRACT,
+    LOCAL_APPEND_ONLY_ANCHOR_TYPE,
+    AnchorVerificationResult,
+    ExternalAnchor,
+    ExternalAnchorError,
+    ExternalAnchorFormatError,
+    ExternalAnchorVerificationError,
+    ExternalAnchorVerifier,
+    artifact_digests_match,
+    normalize_artifact_digest,
+)
+
+__all__ = [
+    "EXTERNAL_ANCHOR_CONTRACT",
+    "LOCAL_APPEND_ONLY_ANCHOR_TYPE",
+    "AnchorVerificationResult",
+    "ExternalAnchor",
+    "ExternalAnchorError",
+    "ExternalAnchorFormatError",
+    "ExternalAnchorVerificationError",
+    "ExternalAnchorVerifier",
+    "LocalAppendOnlyAnchorLog",
+    "artifact_digests_match",
+    "normalize_artifact_digest",
+]

actenon/anchors/local_log.py

@@ -0,0 +1,224 @@
+from __future__ import annotations
+
+import json
+from dataclasses import replace
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Mapping
+from uuid import uuid4
+
+from actenon.core.json import loads_no_duplicate_keys
+from actenon.models.contracts import expect_mapping, format_timestamp, parse_timestamp, utc_now
+from actenon.proof.canonical import sha256_hex
+
+from .models import (
+    EXTERNAL_ANCHOR_CONTRACT,
+    LOCAL_APPEND_ONLY_ANCHOR_TYPE,
+    AnchorVerificationResult,
+    ExternalAnchor,
+    ExternalAnchorFormatError,
+    ExternalAnchorVerificationError,
+    artifact_digests_match,
+    normalize_artifact_digest,
+)
+
+
+LOCAL_ANCHOR_LOG_ENTRY_CONTRACT = {"name": "local_anchor_log_entry", "version": "v1"}
+ENTRY_HASH_ALGORITHM = "sha-256"
+from actenon.proof.canonical import CANONICALIZATION_PROFILE as ENTRY_HASH_CANONICALIZATION
+
+
+def _hash_spec(value: Mapping[str, Any]) -> dict[str, str]:
+    return {
+        "algorithm": ENTRY_HASH_ALGORITHM,
+        "canonicalization": ENTRY_HASH_CANONICALIZATION,
+        "value": sha256_hex(dict(value)),
+    }
+
+
+def _entry_hash_payload(entry: Mapping[str, Any]) -> dict[str, Any]:
+    payload = dict(entry)
+    payload.pop("entry_hash", None)
+    return payload
+
+
+def _compute_entry_hash(entry: Mapping[str, Any]) -> dict[str, str]:
+    return _hash_spec(_entry_hash_payload(entry))
+
+
+def _entry_anchor(entry: Mapping[str, Any]) -> ExternalAnchor:
+    return ExternalAnchor(
+        anchor_id=str(entry["anchor_id"]),
+        anchor_type=str(entry["anchor_type"]),
+        artifact_digest=normalize_artifact_digest(entry["artifact_digest"]),
+        anchored_at=parse_timestamp(entry["anchored_at"], "anchored_at"),
+        log_uri=str(entry["log_uri"]),
+        sequence=int(entry["sequence"]),
+        entry_hash=dict(expect_mapping(entry["entry_hash"], "entry_hash")),
+        previous_entry_hash=dict(expect_mapping(entry["previous_entry_hash"], "previous_entry_hash"))
+        if entry.get("previous_entry_hash") is not None
+        else None,
+        artifact_type=entry.get("artifact_type") if isinstance(entry.get("artifact_type"), str) else None,
+        artifact_id=entry.get("artifact_id") if isinstance(entry.get("artifact_id"), str) else None,
+        metadata=dict(expect_mapping(entry.get("metadata"), "metadata")) if entry.get("metadata") else {},
+    )
+
+
+class LocalAppendOnlyAnchorLog:
+    """JSONL hash-chain for local receipt/refusal durability anchors.
+
+    The log is intentionally local-only. It provides an append-and-verify
+    primitive for development, pilots, and single-node custody workflows. It is
+    not a hosted trust network and does not prevent an operator with filesystem
+    write access from deleting or replacing the whole file.
+    """
+
+    def __init__(self, path: str | Path) -> None:
+        self.path = Path(path)
+
+    @property
+    def log_uri(self) -> str:
+        return self.path.expanduser().resolve().as_uri()
+
+    def anchor_artifact_digest(
+        self,
+        artifact_digest: Mapping[str, Any],
+        *,
+        artifact_type: str | None = None,
+        artifact_id: str | None = None,
+        anchored_at: datetime | None = None,
+        metadata: Mapping[str, Any] | None = None,
+    ) -> ExternalAnchor:
+        digest = normalize_artifact_digest(artifact_digest)
+        existing_entries = self._read_entries(validate_chain=True)
+        previous_hash = existing_entries[-1]["entry_hash"] if existing_entries else None
+        sequence = len(existing_entries) + 1
+        entry: dict[str, Any] = {
+            "contract": dict(LOCAL_ANCHOR_LOG_ENTRY_CONTRACT),
+            "anchor_contract": dict(EXTERNAL_ANCHOR_CONTRACT),
+            "anchor_id": f"anc_local_{uuid4().hex}",
+            "anchor_type": LOCAL_APPEND_ONLY_ANCHOR_TYPE,
+            "artifact_digest": digest,
+            "anchored_at": format_timestamp(anchored_at or utc_now()),
+            "log_uri": self.log_uri,
+            "sequence": sequence,
+            "previous_entry_hash": previous_hash,
+        }
+        if artifact_type is not None:
+            entry["artifact_type"] = artifact_type
+        if artifact_id is not None:
+            entry["artifact_id"] = artifact_id
+        if metadata:
+            entry["metadata"] = dict(metadata)
+        entry["entry_hash"] = _compute_entry_hash(entry)
+        self._append_entry(entry)
+        return _entry_anchor(entry)
+
+    def anchor_attestation(
+        self,
+        attestation: Any,
+        *,
+        anchored_at: datetime | None = None,
+        metadata: Mapping[str, Any] | None = None,
+    ) -> ExternalAnchor:
+        artifact_digest = getattr(attestation, "artifact_digest")
+        artifact_type = getattr(attestation, "artifact_type", None)
+        artifact_id = getattr(attestation, "artifact_id", None)
+        return self.anchor_artifact_digest(
+            artifact_digest,
+            artifact_type=artifact_type,
+            artifact_id=artifact_id,
+            anchored_at=anchored_at,
+            metadata=metadata,
+        )
+
+    def append_anchor_to_attestation(
+        self,
+        attestation: Any,
+        *,
+        anchored_at: datetime | None = None,
+        metadata: Mapping[str, Any] | None = None,
+    ) -> Any:
+        anchor = self.anchor_attestation(
+            attestation,
+            anchored_at=anchored_at,
+            metadata=metadata,
+        )
+        return replace(
+            attestation,
+            external_anchors=[*getattr(attestation, "external_anchors"), anchor.to_dict()],
+        )
+
+    def verify_external_anchor(
+        self,
+        anchor: ExternalAnchor | Mapping[str, Any],
+        *,
+        artifact_digest: Mapping[str, Any],
+    ) -> AnchorVerificationResult:
+        parsed_anchor = anchor if isinstance(anchor, ExternalAnchor) else ExternalAnchor.from_dict(anchor)
+        if parsed_anchor.anchor_type != LOCAL_APPEND_ONLY_ANCHOR_TYPE:
+            raise ExternalAnchorVerificationError(
+                f"unsupported external anchor type {parsed_anchor.anchor_type!r}"
+            )
+        if parsed_anchor.log_uri != self.log_uri:
+            raise ExternalAnchorVerificationError("external anchor points at a different local log")
+        if not artifact_digests_match(parsed_anchor.artifact_digest, artifact_digest):
+            raise ExternalAnchorVerificationError(
+                "external anchor artifact_digest does not match the signed artifact_digest"
+            )
+
+        entries = self._read_entries(validate_chain=True)
+        if parsed_anchor.sequence > len(entries):
+            raise ExternalAnchorVerificationError("external anchor sequence is not present in the local log")
+        entry = entries[parsed_anchor.sequence - 1]
+        entry_anchor = _entry_anchor(entry)
+        if entry_anchor != parsed_anchor:
+            raise ExternalAnchorVerificationError("external anchor does not match the local log entry")
+        return AnchorVerificationResult(anchor=parsed_anchor, anchored_at=parsed_anchor.anchored_at)
+
+    def _append_entry(self, entry: Mapping[str, Any]) -> None:
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        with self.path.open("a", encoding="utf-8") as handle:
+            handle.write(json.dumps(dict(entry), ensure_ascii=False, separators=(",", ":"), sort_keys=True))
+            handle.write("\n")
+
+    def _read_entries(self, *, validate_chain: bool) -> list[dict[str, Any]]:
+        if not self.path.exists():
+            return []
+        entries: list[dict[str, Any]] = []
+        with self.path.open("r", encoding="utf-8") as handle:
+            for line_number, line in enumerate(handle, start=1):
+                stripped = line.strip()
+                if not stripped:
+                    continue
+                try:
+                    entry = loads_no_duplicate_keys(stripped)
+                except ValueError as exc:
+                    raise ExternalAnchorFormatError(
+                        f"local anchor log line {line_number} is not valid JSON"
+                    ) from exc
+                if not isinstance(entry, dict):
+                    raise ExternalAnchorFormatError(
+                        f"local anchor log line {line_number} must be a JSON object"
+                    )
+                entries.append(entry)
+        if validate_chain:
+            self._validate_chain(entries)
+        return entries
+
+    def _validate_chain(self, entries: list[dict[str, Any]]) -> None:
+        previous_hash: dict[str, str] | None = None
+        for index, entry in enumerate(entries, start=1):
+            contract = entry.get("contract")
+            if contract != LOCAL_ANCHOR_LOG_ENTRY_CONTRACT:
+                raise ExternalAnchorFormatError("local anchor log entry contract is unsupported")
+            if entry.get("anchor_type") != LOCAL_APPEND_ONLY_ANCHOR_TYPE:
+                raise ExternalAnchorFormatError("local anchor log entry anchor_type is unsupported")
+            if entry.get("sequence") != index:
+                raise ExternalAnchorFormatError("local anchor log sequence is not contiguous")
+            if entry.get("previous_entry_hash") != previous_hash:
+                raise ExternalAnchorVerificationError("local anchor log hash chain is broken")
+            expected_hash = _compute_entry_hash(entry)
+            if entry.get("entry_hash") != expected_hash:
+                raise ExternalAnchorVerificationError("local anchor log entry hash does not match")
+            previous_hash = expected_hash

actenon/anchors/models.py

@@ -0,0 +1,153 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any, Mapping, Protocol
+
+from actenon.models.contracts import expect_mapping, expect_string, format_timestamp, parse_timestamp
+
+
+EXTERNAL_ANCHOR_CONTRACT = {"name": "external_anchor", "version": "v1"}
+LOCAL_APPEND_ONLY_ANCHOR_TYPE = "local_append_only_log"
+
+
+class ExternalAnchorError(ValueError):
+    """Base class for external anchor parsing and verification errors."""
+
+
+class ExternalAnchorFormatError(ExternalAnchorError):
+    """Raised when an external anchor has an unsupported wire shape."""
+
+
+class ExternalAnchorVerificationError(ExternalAnchorError):
+    """Raised when an external anchor does not verify against its local source."""
+
+
+def normalize_artifact_digest(raw: Mapping[str, Any] | Any) -> dict[str, str]:
+    data = expect_mapping(raw, "artifact_digest")
+    normalized = {
+        "algorithm": expect_string(data.get("algorithm"), "artifact_digest.algorithm"),
+        "value": expect_string(data.get("value"), "artifact_digest.value"),
+    }
+    canonicalization = data.get("canonicalization")
+    if canonicalization is not None:
+        normalized["canonicalization"] = expect_string(
+            canonicalization,
+            "artifact_digest.canonicalization",
+        )
+    return normalized
+
+
+def artifact_digests_match(left: Mapping[str, Any], right: Mapping[str, Any]) -> bool:
+    left_digest = normalize_artifact_digest(left)
+    right_digest = normalize_artifact_digest(right)
+    if left_digest["algorithm"] != right_digest["algorithm"]:
+        return False
+    if left_digest["value"] != right_digest["value"]:
+        return False
+    left_canonicalization = left_digest.get("canonicalization")
+    right_canonicalization = right_digest.get("canonicalization")
+    if left_canonicalization is not None and right_canonicalization is not None:
+        return left_canonicalization == right_canonicalization
+    return True
+
+
+def _parse_hash_spec(raw: Any, field_name: str) -> dict[str, str]:
+    data = expect_mapping(raw, field_name)
+    parsed = {
+        "algorithm": expect_string(data.get("algorithm"), f"{field_name}.algorithm"),
+        "value": expect_string(data.get("value"), f"{field_name}.value"),
+    }
+    canonicalization = data.get("canonicalization")
+    if canonicalization is not None:
+        parsed["canonicalization"] = expect_string(
+            canonicalization,
+            f"{field_name}.canonicalization",
+        )
+    return parsed
+
+
+def _parse_positive_sequence(raw: Any) -> int:
+    if not isinstance(raw, int) or raw <= 0:
+        raise ExternalAnchorFormatError("external anchor sequence must be a positive integer")
+    return raw
+
+
+@dataclass(frozen=True)
+class ExternalAnchor:
+    anchor_id: str
+    anchor_type: str
+    artifact_digest: dict[str, str]
+    anchored_at: datetime
+    log_uri: str
+    sequence: int
+    entry_hash: dict[str, str]
+    previous_entry_hash: dict[str, str] | None = None
+    artifact_type: str | None = None
+    artifact_id: str | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, raw: Mapping[str, Any] | Any) -> "ExternalAnchor":
+        data = expect_mapping(raw, "external_anchor")
+        contract = expect_mapping(data.get("contract"), "external_anchor.contract")
+        if (
+            contract.get("name") != EXTERNAL_ANCHOR_CONTRACT["name"]
+            or contract.get("version") != EXTERNAL_ANCHOR_CONTRACT["version"]
+        ):
+            raise ExternalAnchorFormatError("external anchor contract must declare external_anchor v1")
+        previous_entry_hash = data.get("previous_entry_hash")
+        metadata = data.get("metadata", {})
+        return cls(
+            anchor_id=expect_string(data.get("anchor_id"), "external_anchor.anchor_id"),
+            anchor_type=expect_string(data.get("anchor_type"), "external_anchor.anchor_type"),
+            artifact_digest=normalize_artifact_digest(data.get("artifact_digest")),
+            anchored_at=parse_timestamp(data.get("anchored_at"), "external_anchor.anchored_at"),
+            log_uri=expect_string(data.get("log_uri"), "external_anchor.log_uri"),
+            sequence=_parse_positive_sequence(data.get("sequence")),
+            entry_hash=_parse_hash_spec(data.get("entry_hash"), "external_anchor.entry_hash"),
+            previous_entry_hash=_parse_hash_spec(previous_entry_hash, "external_anchor.previous_entry_hash")
+            if previous_entry_hash is not None
+            else None,
+            artifact_type=data.get("artifact_type") if isinstance(data.get("artifact_type"), str) else None,
+            artifact_id=data.get("artifact_id") if isinstance(data.get("artifact_id"), str) else None,
+            metadata=dict(expect_mapping(metadata, "external_anchor.metadata")) if metadata else {},
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        payload: dict[str, Any] = {
+            "contract": dict(EXTERNAL_ANCHOR_CONTRACT),
+            "anchor_id": self.anchor_id,
+            "anchor_type": self.anchor_type,
+            "artifact_digest": dict(self.artifact_digest),
+            "anchored_at": format_timestamp(self.anchored_at),
+            "log_uri": self.log_uri,
+            "sequence": self.sequence,
+            "entry_hash": dict(self.entry_hash),
+        }
+        if self.previous_entry_hash is not None:
+            payload["previous_entry_hash"] = dict(self.previous_entry_hash)
+        if self.artifact_type is not None:
+            payload["artifact_type"] = self.artifact_type
+        if self.artifact_id is not None:
+            payload["artifact_id"] = self.artifact_id
+        if self.metadata:
+            payload["metadata"] = dict(self.metadata)
+        return payload
+
+
+@dataclass(frozen=True)
+class AnchorVerificationResult:
+    anchor: ExternalAnchor
+    anchored_at: datetime
+    status: str = "verified"
+
+
+class ExternalAnchorVerifier(Protocol):
+    def verify_external_anchor(
+        self,
+        anchor: ExternalAnchor | Mapping[str, Any],
+        *,
+        artifact_digest: Mapping[str, Any],
+    ) -> AnchorVerificationResult:
+        """Verify an external anchor against the expected signed artifact digest."""

actenon/api/__init__.py

@@ -0,0 +1,12 @@
+"""Intake services for external action-intent payloads."""
+
+from .invoice_payment import build_invoice_payment_action_intent_payload, compute_invoice_payment_batch_hash
+from .intake import ActionIntentIntakeService
+from .refund import build_refund_action_intent_payload
+
+__all__ = [
+    "ActionIntentIntakeService",
+    "build_invoice_payment_action_intent_payload",
+    "build_refund_action_intent_payload",
+    "compute_invoice_payment_batch_hash",
+]

actenon/api/intake.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from typing import Any, Mapping
+
+from actenon.core.errors import ContractValidationError
+from actenon.models.contracts import ActionIntent, Violation
+
+
+class ActionIntentIntakeService:
+    """Parses and validates external Action Intent payloads."""
+
+    def parse(self, payload: Mapping[str, Any]) -> ActionIntent:
+        try:
+            intent = ActionIntent.from_dict(payload)
+        except ValueError as exc:
+            violation = Violation(code="INVALID_CONTRACT", message=str(exc))
+            raise ContractValidationError("Action Intent contract validation failed", violations=(violation,)) from exc
+
+        violations: list[Violation] = []
+        if intent.expires_at <= intent.issued_at:
+            violations.append(
+                Violation(
+                    code="INVALID_WINDOW",
+                    field_path="expires_at",
+                    message="expires_at must be later than issued_at",
+                )
+            )
+        if not intent.action.parameters:
+            violations.append(
+                Violation(
+                    code="MISSING_ACTION_PARAMETERS",
+                    field_path="action.parameters",
+                    message="action.parameters must contain at least one value",
+                )
+            )
+        if violations:
+            raise ContractValidationError("Action Intent semantic validation failed", violations=tuple(violations))
+        return intent
+

actenon/api/invoice_payment.py

@@ -0,0 +1,143 @@
+from __future__ import annotations
+
+from datetime import date, datetime, timedelta
+from typing import Any, Iterable
+
+from actenon.proof.canonical import sha256_hex
+
+
+def normalize_invoice_ids(invoice_ids: Iterable[str]) -> list[str]:
+    normalized = sorted({str(item) for item in invoice_ids if str(item)})
+    if not normalized:
+        raise ValueError("invoice_ids must contain at least one non-empty value")
+    return normalized
+
+
+def normalize_payment_date(value: date | str) -> str:
+    if isinstance(value, date):
+        return value.isoformat()
+    parsed = date.fromisoformat(value)
+    return parsed.isoformat()
+
+
+def compute_invoice_payment_batch_hash(
+    *,
+    payer_entity_id: str,
+    supplier_id: str,
+    bank_account_reference: str,
+    invoice_ids: Iterable[str],
+    amount_minor: int,
+    currency: str,
+    payment_date: date | str,
+    payment_batch_id: str,
+) -> str:
+    hash_input = {
+        "payer_entity_id": payer_entity_id,
+        "supplier_id": supplier_id,
+        "bank_account_reference": bank_account_reference,
+        "invoice_ids": normalize_invoice_ids(invoice_ids),
+        "amount_minor": amount_minor,
+        "currency": currency,
+        "payment_date": normalize_payment_date(payment_date),
+        "payment_batch_id": payment_batch_id,
+    }
+    return f"batch_{sha256_hex(hash_input)}"
+
+
+def build_invoice_payment_action_intent_payload(
+    *,
+    intent_id: str,
+    tenant_id: str,
+    requester_id: str,
+    payer_entity_id: str,
+    supplier_id: str,
+    bank_account_reference: str,
+    invoice_ids: Iterable[str],
+    amount_minor: int,
+    currency: str,
+    payment_date: date | str,
+    payment_batch_id: str,
+    issued_at: datetime,
+    proposer_id: str | None = None,
+    ttl_seconds: int = 300,
+    justification: str | None = None,
+    evidence_refs: list[dict[str, Any]] | None = None,
+    context: dict[str, Any] | None = None,
+    metadata: dict[str, Any] | None = None,
+    batch_hash: str | None = None,
+) -> dict[str, Any]:
+    normalized_invoice_ids = normalize_invoice_ids(invoice_ids)
+    normalized_payment_date = normalize_payment_date(payment_date)
+    resolved_batch_hash = batch_hash or compute_invoice_payment_batch_hash(
+        payer_entity_id=payer_entity_id,
+        supplier_id=supplier_id,
+        bank_account_reference=bank_account_reference,
+        invoice_ids=normalized_invoice_ids,
+        amount_minor=amount_minor,
+        currency=currency,
+        payment_date=normalized_payment_date,
+        payment_batch_id=payment_batch_id,
+    )
+    resolved_proposer_id = proposer_id or requester_id
+    idempotency_key_input = {
+        "payment_batch_id": payment_batch_id,
+        "invoice_ids": normalized_invoice_ids,
+        "amount_minor": amount_minor,
+        "currency": currency,
+        "payer_entity_id": payer_entity_id,
+        "supplier_id": supplier_id,
+    }
+    idempotency_key = f"ipy_{sha256_hex(idempotency_key_input)}"
+    expires_at = issued_at + timedelta(seconds=ttl_seconds)
+
+    payload: dict[str, Any] = {
+        "contract": {"name": "action_intent", "version": "v1"},
+        "intent_id": intent_id,
+        "idempotency_key": idempotency_key,
+        "issued_at": issued_at.isoformat().replace("+00:00", "Z"),
+        "expires_at": expires_at.isoformat().replace("+00:00", "Z"),
+        "tenant": {"tenant_id": tenant_id},
+        "requester": {"type": "service", "id": requester_id},
+        "action": {
+            "name": "invoice_payment.execute",
+            "capability": "invoice_payment.execute",
+            "parameters": {
+                "payer_entity_id": payer_entity_id,
+                "supplier_id": supplier_id,
+                "bank_account_reference": bank_account_reference,
+                "invoice_ids": normalized_invoice_ids,
+                "amount_minor": amount_minor,
+                "currency": currency,
+                "payment_date": normalized_payment_date,
+                "payment_batch_id": payment_batch_id,
+                "batch_hash": resolved_batch_hash,
+                "proposer_id": resolved_proposer_id,
+            },
+            "constraints": {
+                "exact_payer_entity_id": payer_entity_id,
+                "exact_supplier_id": supplier_id,
+                "exact_bank_account_reference": bank_account_reference,
+                "exact_invoice_ids": normalized_invoice_ids,
+                "exact_amount_minor": amount_minor,
+                "exact_currency": currency,
+                "exact_payment_date": normalized_payment_date,
+                "exact_payment_batch_id": payment_batch_id,
+                "exact_batch_hash": resolved_batch_hash,
+            },
+            "scope": {
+                "target_resource_type": "payment_batch",
+                "single_use": True,
+            },
+        },
+        "target": {
+            "resource_type": "payment_batch",
+            "resource_id": payment_batch_id,
+        },
+        "context": context or {},
+        "metadata": metadata or {},
+    }
+    if justification is not None:
+        payload["justification"] = justification
+    if evidence_refs:
+        payload["evidence_refs"] = evidence_refs
+    return payload

actenon/api/refund.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+from datetime import datetime, timedelta
+from typing import Any
+
+
+def build_refund_action_intent_payload(
+    *,
+    intent_id: str,
+    tenant_id: str,
+    requester_id: str,
+    payment_id: str,
+    amount_minor: int,
+    currency: str,
+    issued_at: datetime,
+    ttl_seconds: int = 300,
+    justification: str | None = None,
+    metadata: dict[str, Any] | None = None,
+    context: dict[str, Any] | None = None,
+    evidence_refs: list[dict[str, Any]] | None = None,
+) -> dict[str, Any]:
+    expires_at = issued_at + timedelta(seconds=ttl_seconds)
+    payload: dict[str, Any] = {
+        "contract": {"name": "action_intent", "version": "v1"},
+        "intent_id": intent_id,
+        "issued_at": issued_at.isoformat().replace("+00:00", "Z"),
+        "expires_at": expires_at.isoformat().replace("+00:00", "Z"),
+        "tenant": {"tenant_id": tenant_id},
+        "requester": {"type": "service", "id": requester_id},
+        "action": {
+            "name": "refund.create",
+            "capability": "refund.execute",
+            "parameters": {
+                "amount_minor": amount_minor,
+                "currency": currency,
+            },
+            "constraints": {
+                "exact_amount_minor": amount_minor,
+                "exact_currency": currency,
+            },
+            "scope": {
+                "target_resource_type": "payment",
+                "single_use": True,
+            },
+        },
+        "target": {
+            "resource_type": "payment",
+            "resource_id": payment_id,
+        },
+        "metadata": metadata or {},
+        "context": context or {},
+    }
+    if justification is not None:
+        payload["justification"] = justification
+    if evidence_refs:
+        payload["evidence_refs"] = evidence_refs
+    return payload