diff --git a/.github/workflows/protocol-installed-test.yml b/.github/workflows/protocol-installed-test.yml index c535c8a..60125e0 100644 --- a/.github/workflows/protocol-installed-test.yml +++ b/.github/workflows/protocol-installed-test.yml @@ -32,7 +32,7 @@ jobs: matrix: os: - ubuntu-24.04 - - macos-14 + - macos-15 - windows-2022 python: - "3.11" diff --git a/src/stateforge_protocol/sfp/operation_admission/v1/contract.py b/src/stateforge_protocol/sfp/operation_admission/v1/contract.py index 79ec016..ba5c075 100644 --- a/src/stateforge_protocol/sfp/operation_admission/v1/contract.py +++ b/src/stateforge_protocol/sfp/operation_admission/v1/contract.py @@ -1,5 +1,6 @@ """Expose the normative SFP Operation Admission v1 wire contract.""" +from dataclasses import dataclass from typing import Final from stateforge_protocol.sfp.operation_admission.v1 import ( @@ -22,3 +23,49 @@ # Contract-context limits mirrored by the packaged validation schema. MAX_REQUIRED_IMPLEMENTATION_ROLES: Final = 16 + + +@dataclass(frozen=True, slots=True) +class AdmissionErrorContract: + """Bind one structured rejection reason to its transport semantics.""" + + grpc_status: str + retryable: bool + + +def _reason(name: str) -> int: + return operation_admission_pb2.AdmissionErrorReason.Value(name) + + +ADMISSION_ERROR_CONTRACTS: Final = { + _reason("ADMISSION_ERROR_REASON_INVALID_OPERATION_REQUEST"): ( + AdmissionErrorContract("INVALID_ARGUMENT", False) + ), + _reason("ADMISSION_ERROR_REASON_OPERATION_NOT_DECLARED"): ( + AdmissionErrorContract("UNIMPLEMENTED", False) + ), + _reason("ADMISSION_ERROR_REASON_OPERATION_INCOMPATIBLE"): ( + AdmissionErrorContract("FAILED_PRECONDITION", False) + ), + _reason("ADMISSION_ERROR_REASON_OPERATION_PRECONDITION_FAILED"): ( + AdmissionErrorContract("FAILED_PRECONDITION", True) + ), + _reason("ADMISSION_ERROR_REASON_PROVIDER_CAPACITY_EXHAUSTED"): ( + AdmissionErrorContract("RESOURCE_EXHAUSTED", True) + ), + _reason("ADMISSION_ERROR_REASON_PROVIDER_UNAVAILABLE"): ( + AdmissionErrorContract("UNAVAILABLE", True) + ), + _reason("ADMISSION_ERROR_REASON_IDEMPOTENCY_CONFLICT"): ( + AdmissionErrorContract("ALREADY_EXISTS", False) + ), + _reason("ADMISSION_ERROR_REASON_OPERATION_DEADLINE_EXPIRED"): ( + AdmissionErrorContract("DEADLINE_EXCEEDED", False) + ), + _reason("ADMISSION_ERROR_REASON_OPERATION_RECORD_UNAVAILABLE"): ( + AdmissionErrorContract("FAILED_PRECONDITION", False) + ), + _reason("ADMISSION_ERROR_REASON_OPERATION_RECORD_EXPIRED"): ( + AdmissionErrorContract("FAILED_PRECONDITION", False) + ), +} diff --git a/src/stateforge_protocol/sfp/operation_admission/v1/validation.py b/src/stateforge_protocol/sfp/operation_admission/v1/validation.py index 59b6f6f..f3a6c79 100644 --- a/src/stateforge_protocol/sfp/operation_admission/v1/validation.py +++ b/src/stateforge_protocol/sfp/operation_admission/v1/validation.py @@ -18,6 +18,7 @@ "validate_admission_error_detail", "validate_admission_exchange", "validate_admission_record", + "validate_admission_rejection", "validate_start_operation_request", "validate_start_operation_response", ] @@ -147,6 +148,30 @@ def validate_admission_error_detail( ) +def validate_admission_rejection( + detail: operation_admission_pb2.OperationAdmissionErrorDetail, + *, + grpc_status: str, +) -> None: + """Validate structured rejection detail and its gRPC status together.""" + validate_admission_error_detail(detail) + error_contract = contract.ADMISSION_ERROR_CONTRACTS.get(detail.reason) + if error_contract is None: + raise OperationAdmissionValidationError( + "error: reason has no canonical rejection contract" + ) + _VALIDATION.require_equal( + grpc_status, + error_contract.grpc_status, + "error: gRPC status does not match reason", + ) + _VALIDATION.require_equal( + detail.retryable, + error_contract.retryable, + "error: retryable does not match reason", + ) + + def validate_admission_exchange( request: operation_admission_pb2.StartOperationRequest, response: operation_admission_pb2.StartOperationResponse, diff --git a/tests/test_operation_admission_contract.py b/tests/test_operation_admission_contract.py index 426f990..7cdbb72 100644 --- a/tests/test_operation_admission_contract.py +++ b/tests/test_operation_admission_contract.py @@ -466,6 +466,21 @@ def test_error_fixture_covers_every_reason_and_creates_no_record() -> None: "UNAVAILABLE", "UNIMPLEMENTED", } + assert set(contract.ADMISSION_ERROR_CONTRACTS) == { + value.number + for value in ( + operation_admission_pb2.AdmissionErrorReason.DESCRIPTOR.values + ) + if value.number != 0 + } + + for case in cases: + reason = operation_admission_pb2.AdmissionErrorReason.Value( + case["reason"] + ) + error_contract = contract.ADMISSION_ERROR_CONTRACTS[reason] + assert error_contract.grpc_status == case["grpcStatus"] + assert error_contract.retryable is case["retryable"] @pytest.mark.parametrize("case", _read_json("error-cases.json")) @@ -484,6 +499,10 @@ def test_error_detail_round_trips_for_every_documented_case(case) -> None: operation_admission_pb2.OperationAdmissionErrorDetail(), ) admission_validation.validate_admission_error_detail(message) + admission_validation.validate_admission_rejection( + message, + grpc_status=case["grpcStatus"], + ) projected = json_format.MessageToDict( message, always_print_fields_with_no_presence=True, @@ -492,6 +511,49 @@ def test_error_detail_round_trips_for_every_documented_case(case) -> None: assert projected == detail +def test_rejection_rejects_status_that_does_not_match_reason() -> None: + detail = json_format.ParseDict( + { + "operationId": "22222222-2222-4222-8222-222222222222", + "reason": "ADMISSION_ERROR_REASON_PROVIDER_UNAVAILABLE", + "retryable": True, + "retryAfter": "5s", + "explanation": "Provider is temporarily unavailable.", + }, + operation_admission_pb2.OperationAdmissionErrorDetail(), + ) + + with pytest.raises( + admission_validation.OperationAdmissionValidationError, + match="gRPC status does not match reason", + ): + admission_validation.validate_admission_rejection( + detail, + grpc_status="FAILED_PRECONDITION", + ) + + +def test_rejection_rejects_retryable_that_does_not_match_reason() -> None: + detail = json_format.ParseDict( + { + "operationId": "22222222-2222-4222-8222-222222222222", + "reason": "ADMISSION_ERROR_REASON_PROVIDER_UNAVAILABLE", + "retryable": False, + "explanation": "Provider is temporarily unavailable.", + }, + operation_admission_pb2.OperationAdmissionErrorDetail(), + ) + + with pytest.raises( + admission_validation.OperationAdmissionValidationError, + match="retryable does not match reason", + ): + admission_validation.validate_admission_rejection( + detail, + grpc_status="UNAVAILABLE", + ) + + def test_retry_after_is_forbidden_for_non_retryable_error() -> None: detail = { "operationId": "22222222-2222-4222-8222-222222222222",