Shared contracts

The raes_contracts package owns shared data types and enums. The processor, runtime, backend protocols, conformance tools, and authoring tools use them. They define the typed boundary for runtime calls to backends. Keep them out of runtime and processor modules.

For exact portable structures, use the published schema reference for RAES 11.0.2. The normative specification index links to required meaning. The Python API supplies implementation evidence. It does not replace either authority.

Diagnostics

Shared diagnostic contracts.

class raes_contracts.diagnostics.Diagnostic

Bases: object

Structured planner/runtime message.

code: str
domain: str
address: str
message: str
severity: Severity = 'error'
property is_error: bool
__init__(code, domain, address, message, severity=Severity.ERROR)
Parameters:
  • code (str)

  • domain (str)

  • address (str)

  • message (str)

  • severity (Severity)

Return type:

None

class raes_contracts.diagnostics.DiagnosticModel

Bases: BaseModel

Closed portable diagnostic shape for published contracts.

model_config = {'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

code: str
domain: str
address: str
message: str
severity: Severity
class raes_contracts.diagnostics.Severity

Bases: str, Enum

Diagnostic severity level.

ERROR = 'error'
WARNING = 'warning'
INFO = 'info'
__new__(value)
raes_contracts.diagnostics.diagnostic_model(diagnostic)

Convert the internal immutable diagnostic to its closed contract model.

Parameters:

diagnostic (Diagnostic)

Return type:

DiagnosticModel

raes_contracts.diagnostics.diagnostic_payload(diagnostic)

Render a diagnostic as a JSON-ready mapping (severity as its string value).

Parameters:

diagnostic (Diagnostic)

Return type:

dict[str, Any]

raes_contracts.diagnostics.portable_diagnostic_payload(diagnostic)

Render a diagnostic through the closed portable JSON contract.

Internal diagnostic addresses predate the transport contract and may use dotted runtime locations. Preserve that value as one escaped JSON-Pointer token instead of weakening the public address grammar.

Parameters:

diagnostic (Diagnostic)

Return type:

dict[str, Any]

Artifact transformation reports

Closed portable reports for pure RAES artifact transformations.

class raes_contracts.contracts.artifact_transformations.ArtifactTransformationCheckModel

Bases: ContractModel

model_config = {'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

check_id: str
outcome: TransformationCheckOutcome
diagnostic_codes: tuple[str, ...]
class raes_contracts.contracts.artifact_transformations.ArtifactTransformationIdentityMapModel

Bases: ContractModel

model_config = {'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

declaration_kind: NonEmptyString
before: NonEmptyString
after: NonEmptyString
class raes_contracts.contracts.artifact_transformations.ArtifactTransformationKind

Bases: str, Enum

SDL_AUTHORING = 'sdl-authoring'
SDL_MATERIALIZATION = 'sdl-materialization'
PORTABLE_CONTRACT = 'portable-contract'
__new__(value)
class raes_contracts.contracts.artifact_transformations.ArtifactTransformationLossKind

Bases: str, Enum

DECLARATION_REMOVED = 'declaration-removed'
SEMANTIC_OMISSION = 'semantic-omission'
__new__(value)
class raes_contracts.contracts.artifact_transformations.ArtifactTransformationLossModel

Bases: ContractModel

model_config = {'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

kind: ArtifactTransformationLossKind
affected_identity: NonEmptyString
diagnostic: DiagnosticModel
class raes_contracts.contracts.artifact_transformations.ArtifactTransformationPreservationModel

Bases: ContractModel

model_config = {'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

profile: NonEmptyString
outcome: PreservationOutcome
evidence_digests: tuple[PrefixedDigestString, ...]
limitations: tuple[NonEmptyString, ...]
class raes_contracts.contracts.artifact_transformations.ArtifactTransformationReportModel

Bases: ContractModel

Deterministic all-or-none report for one semantic operation.

model_config = {'extra': 'forbid', 'frozen': True, 'title': 'RAES Artifact Transformation Report v1'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

schema_version: Literal[ARTIFACT_TRANSFORMATION_REPORT_SCHEMA_VERSION]
operation_profile: str
status: ArtifactTransformationStatus
artifact_kind: ArtifactTransformationKind
source_profile: NonEmptyString
target_profile: NonEmptyString
canonicalization_profile: NonEmptyString
source_digest: PrefixedDigestString
target_digest: PrefixedDigestString | None
policy_digest: PrefixedDigestString
derivation_digest: PrefixedDigestString
preconditions: tuple[ArtifactTransformationCheckModel, ...]
postconditions: tuple[ArtifactTransformationCheckModel, ...]
affected_identities: tuple[NonEmptyString, ...]
identity_map: tuple[ArtifactTransformationIdentityMapModel, ...]
preservation: ArtifactTransformationPreservationModel
losses: tuple[ArtifactTransformationLossModel, ...]
diagnostics: tuple[DiagnosticModel, ...]
class raes_contracts.contracts.artifact_transformations.ArtifactTransformationStatus

Bases: str, Enum

SUCCESS = 'success'
REFUSED = 'refused'
__new__(value)
class raes_contracts.contracts.artifact_transformations.PreservationOutcome

Bases: str, Enum

VERIFIED = 'verified'
FAILED = 'failed'
NOT_APPLICABLE = 'not-applicable'
__new__(value)
class raes_contracts.contracts.artifact_transformations.TransformationCheckOutcome

Bases: str, Enum

PASSED = 'passed'
FAILED = 'failed'
NOT_APPLICABLE = 'not-applicable'
__new__(value)

Planning

Native planning carriers; safe accessors return None for missing or inapplicable surfaces without validating.

class raes_contracts.planning.ChangeAction

Bases: str, Enum

Planner reconciliation result for a resource.

CREATE = 'create'
UPDATE = 'update'
DELETE = 'delete'
UNCHANGED = 'unchanged'
__new__(value)
class raes_contracts.planning.EvaluationOp

Bases: PlanOperation

Evaluation reconciliation operation.

class raes_contracts.planning.EvaluationPlan

Bases: object

Resolved evaluation graph and reconciliation actions.

safe_states: tuple[ResolvedSafeState, ...] = ()
resources: dict[str, PlannedResource]
operations: list[EvaluationOp]
startup_order: list[str]
diagnostics: list[Diagnostic]
observation_demands: tuple[EffectiveObservationDemand, ...] = ()
run_id: str | None = None
instantiation_id: str | None = None
purpose: Literal['execution', 'inspection'] = 'execution'
materialization_source: MaterializationSource | None = None
augmentation_scope_required: bool = False
operation_id: str | None = None
property actionable_operations: list[EvaluationOp]
__init__(resources=<factory>, operations=<factory>, startup_order=<factory>, diagnostics=<factory>, observation_demands=(), run_id=None, instantiation_id=None, purpose='execution', materialization_source=None, augmentation_scope_required=False, operation_id=None, *, safe_states=())
Parameters:
  • resources (dict[str, PlannedResource])

  • operations (list[EvaluationOp])

  • startup_order (list[str])

  • diagnostics (list[Diagnostic])

  • observation_demands (tuple[EffectiveObservationDemand, ...])

  • run_id (str | None)

  • instantiation_id (str | None)

  • purpose (Literal['execution', 'inspection'])

  • materialization_source (MaterializationSource | None)

  • augmentation_scope_required (bool)

  • operation_id (str | None)

  • safe_states (tuple[ResolvedSafeState, ...])

Return type:

None

class raes_contracts.planning.OrchestrationOp

Bases: PlanOperation

Orchestration reconciliation operation.

class raes_contracts.planning.OrchestrationPlan

Bases: object

Resolved orchestration graph and reconciliation actions.

safe_states: tuple[ResolvedSafeState, ...] = ()
resources: dict[str, PlannedResource]
operations: list[OrchestrationOp]
startup_order: list[str]
diagnostics: list[Diagnostic]
observation_demands: tuple[EffectiveObservationDemand, ...] = ()
purpose: Literal['execution', 'inspection'] = 'execution'
materialization_source: MaterializationSource | None = None
augmentation_scope_required: bool = False
operation_id: str | None = None
property actionable_operations: list[OrchestrationOp]
__init__(resources=<factory>, operations=<factory>, startup_order=<factory>, diagnostics=<factory>, observation_demands=(), purpose='execution', materialization_source=None, augmentation_scope_required=False, operation_id=None, *, safe_states=())
Parameters:
  • resources (dict[str, PlannedResource])

  • operations (list[OrchestrationOp])

  • startup_order (list[str])

  • diagnostics (list[Diagnostic])

  • observation_demands (tuple[EffectiveObservationDemand, ...])

  • purpose (Literal['execution', 'inspection'])

  • materialization_source (MaterializationSource | None)

  • augmentation_scope_required (bool)

  • operation_id (str | None)

  • safe_states (tuple[ResolvedSafeState, ...])

Return type:

None

class raes_contracts.planning.PlanOperation

Bases: object

A reconciliation operation for a planned resource.

action: ChangeAction
address: str
resource_type: str
payload: dict[str, Any]
ordering_dependencies: tuple[str, ...] = ()
refresh_dependencies: tuple[str, ...] = ()
execution_policy: EffectiveExecutionPolicy | None = None
execution_policy_scopes: tuple[EffectiveExecutionPolicy, ...] = ()
__init__(action, address, resource_type, payload, ordering_dependencies=(), refresh_dependencies=(), *, execution_policy=None, execution_policy_scopes=())
Parameters:
  • action (ChangeAction)

  • address (str)

  • resource_type (str)

  • payload (dict[str, Any])

  • ordering_dependencies (tuple[str, ...])

  • refresh_dependencies (tuple[str, ...])

  • execution_policy (EffectiveExecutionPolicy | None)

  • execution_policy_scopes (tuple[EffectiveExecutionPolicy, ...])

Return type:

None

class raes_contracts.planning.PlanScope

Bases: object

Identity of the realization a plan is computed for.

target_name selects the backend target the plan is reconciled against, while run_id names the authoritative run scope (run:<id> authority) and instantiation_id names the unique instantiation coordinate; together the run/instantiation pair lets per-run / per-instantiation generated values reconcile against the correct scope (issue #1276). Both identifiers are value-free scope identities, never the generated secret. Bundling the three keeps the planning entry points cohesive rather than threading loose optional identifiers through every signature.

target_name: str | None = None
run_id: str | None = None
instantiation_id: str | None = None
__init__(target_name=None, run_id=None, instantiation_id=None)
Parameters:
  • target_name (str | None)

  • run_id (str | None)

  • instantiation_id (str | None)

Return type:

None

class raes_contracts.planning.PlannedResource

Bases: object

Normalized resource used by the planner and snapshot.

address: str
domain: RuntimeDomain
resource_type: str
payload: dict[str, Any]
ordering_dependencies: tuple[str, ...] = ()
refresh_dependencies: tuple[str, ...] = ()
profile_bindings: tuple[DomainProfileBindingModel, ...] = ()
__init__(address, domain, resource_type, payload, ordering_dependencies=(), refresh_dependencies=(), profile_bindings=())
Parameters:
  • address (str)

  • domain (RuntimeDomain)

  • resource_type (str)

  • payload (dict[str, Any])

  • ordering_dependencies (tuple[str, ...])

  • refresh_dependencies (tuple[str, ...])

  • profile_bindings (tuple[DomainProfileBindingModel, ...])

Return type:

None

class raes_contracts.planning.ProvisionOp

Bases: PlanOperation

Provisioning reconciliation operation.

profile_bindings: tuple[DomainProfileBindingModel, ...] = ()
__init__(action, address, resource_type, payload, ordering_dependencies=(), refresh_dependencies=(), profile_bindings=(), *, execution_policy=None, execution_policy_scopes=())
Parameters:
  • action (ChangeAction)

  • address (str)

  • resource_type (str)

  • payload (dict[str, Any])

  • ordering_dependencies (tuple[str, ...])

  • refresh_dependencies (tuple[str, ...])

  • profile_bindings (tuple[DomainProfileBindingModel, ...])

  • execution_policy (EffectiveExecutionPolicy | None)

  • execution_policy_scopes (tuple[EffectiveExecutionPolicy, ...])

Return type:

None

class raes_contracts.planning.ProvisioningPlan

Bases: object

Provisioning plan over canonical deployment resources.

safe_states: tuple[ResolvedSafeState, ...] = ()
resources: dict[str, PlannedResource]
operations: list[ProvisionOp]
diagnostics: list[Diagnostic]
realization_authority: tuple[ResolvedRealizationAuthority, ...] = ()
realization_envelope: RealizationEnvelopeIdentityModel | None = None
realization_constraints: tuple[PlannedRealizationConstraint, ...] = ()
operation_id: str | None = None
observation_demands: tuple[EffectiveObservationDemand, ...] = ()
preparation: RealizationPreparationAuthority | None = None
profile_authority: PlanProfileAuthority | None = None
run_id: str | None = None
instantiation_id: str | None = None
purpose: Literal['execution', 'inspection'] = 'execution'
materialization_source: MaterializationSource | None = None
augmentation_scope_required: bool = False
inventory_attempt_id: str | None = None
inventory_refresh: bool = False
property actionable_operations: list[ProvisionOp]
__init__(resources=<factory>, operations=<factory>, diagnostics=<factory>, realization_authority=(), realization_envelope=None, realization_constraints=(), operation_id=None, observation_demands=(), preparation=None, profile_authority=None, run_id=None, instantiation_id=None, purpose='execution', materialization_source=None, augmentation_scope_required=False, inventory_attempt_id=None, inventory_refresh=False, *, safe_states=())
Parameters:
  • resources (dict[str, PlannedResource])

  • operations (list[ProvisionOp])

  • diagnostics (list[Diagnostic])

  • realization_authority (tuple[ResolvedRealizationAuthority, ...])

  • realization_envelope (RealizationEnvelopeIdentityModel | None)

  • realization_constraints (tuple[PlannedRealizationConstraint, ...])

  • operation_id (str | None)

  • observation_demands (tuple[EffectiveObservationDemand, ...])

  • preparation (RealizationPreparationAuthority | None)

  • profile_authority (PlanProfileAuthority | None)

  • run_id (str | None)

  • instantiation_id (str | None)

  • purpose (Literal['execution', 'inspection'])

  • materialization_source (MaterializationSource | None)

  • augmentation_scope_required (bool)

  • inventory_attempt_id (str | None)

  • inventory_refresh (bool)

  • safe_states (tuple[ResolvedSafeState, ...])

Return type:

None

class raes_contracts.planning.RealizationAuthorityBound

Bases: object

One publication-safe typed bound over a concern value or owned leaf.

value_pointer: str
domain: Annotated[ExactDomain | EnumDomain | BooleanDomain | NumericIntervalDomain | GovernedReferenceDomain | RecordDomain, FieldInfo(annotation=NoneType, required=True, discriminator='kind')]
identity_digest: str | None = None
__init__(value_pointer, domain, identity_digest=None)
Parameters:
  • value_pointer (str)

  • domain (Annotated[ExactDomain | EnumDomain | BooleanDomain | NumericIntervalDomain | GovernedReferenceDomain | RecordDomain, FieldInfo(annotation=NoneType, required=True, discriminator='kind')])

  • identity_digest (str | None)

Return type:

None

class raes_contracts.planning.RealizationAuthorityMode

Bases: str, Enum

Resolved author permission for one portable realization concern.

CLOSED = 'closed'
OPEN = 'open'
CONSTRAINED = 'constrained'
EXACT = 'exact'
__new__(value)
class raes_contracts.planning.RealizationPreparationAuthority

Bases: ContractModel

Conditional execution authority sealed into the original authenticated plan.

model_config = {'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

contract_id: Literal['backend-realization-preparation-v1']
manifest_digest: str
node_collection: PreparedNodeCollectionAuthority | None
class raes_contracts.planning.RealizationResolutionSource

Bases: str, Enum

Canonical source that supplied a resolved realization decision.

AUTHORED_LEAF = 'authored-leaf'
AUTHORED_SCOPE = 'authored-scope'
APPARATUS_DEFAULT = 'apparatus-default'
LEGACY_DEFAULT = 'legacy-default'
PROCESSOR_DERIVED = 'processor-derived'
__new__(value)
class raes_contracts.planning.ResolvedRealizationAuthority

Bases: object

Portable, value-safe author boundary for one planned concern.

address: str
field_path: str
domain: str
requirement_kind: str
payload_pointer: str
mode: RealizationAuthorityMode
source: RealizationResolutionSource
provenance: ExplicitnessProvenance = 'author-declared'
governing_scope: str | None = None
bounds: tuple[RealizationAuthorityBound, ...] = ()
verification_scope: RealizationVerificationScope | None = None
required_observation_strength: ObservationStrength | None = None
structure: Annotated[ExactRealizationValue | OpenRealizationValue | RealizationRecord | RealizationCollection, FieldInfo(annotation=NoneType, required=True, discriminator='kind')] | None = None
constraint_document: RealizationConstraintDocument | None = None
constraint_binding: str | None = None
__init__(address, field_path, domain, requirement_kind, payload_pointer, mode, source, provenance=ExplicitnessProvenance.AUTHOR_DECLARED, governing_scope=None, bounds=(), verification_scope=None, required_observation_strength=None, structure=None, constraint_document=None, constraint_binding=None)
Parameters:
  • address (str)

  • field_path (str)

  • domain (str)

  • requirement_kind (str)

  • payload_pointer (str)

  • mode (RealizationAuthorityMode)

  • source (RealizationResolutionSource)

  • provenance (ExplicitnessProvenance)

  • governing_scope (str | None)

  • bounds (tuple[RealizationAuthorityBound, ...])

  • verification_scope (RealizationVerificationScope | None)

  • required_observation_strength (ObservationStrength | None)

  • structure (Annotated[ExactRealizationValue | OpenRealizationValue | RealizationRecord | RealizationCollection, FieldInfo(annotation=NoneType, required=True, discriminator='kind')] | None)

  • constraint_document (RealizationConstraintDocument | None)

  • constraint_binding (str | None)

Return type:

None

class raes_contracts.planning.RuntimeDomain

Bases: str, Enum

Top-level runtime concern.

PROVISIONING = 'provisioning'
ORCHESTRATION = 'orchestration'
EVALUATION = 'evaluation'
PARTICIPANT = 'participant'
__new__(value)
raes_contracts.planning.planned_infrastructure_spec(resource)

Return spec.infrastructure for a provisioning node or network.

Infrastructure is intentionally unavailable for other provisioning resource types and for other runtime domains rather than being inferred from a coincidentally similar payload shape.

Parameters:

resource (PlannedResource)

Return type:

Mapping[str, Any] | None

raes_contracts.planning.planned_node_resources(resource)

Return a provisioning node’s authored resources mapping, if present.

Parameters:

resource (PlannedResource)

Return type:

Mapping[str, Any] | None

raes_contracts.planning.planned_node_source(resource)

Return a provisioning node’s authored string-or-mapping source.

Mapping sources retain all source/build inputs and are not collapsed to a backend-specific image name. Empty strings and unsupported value shapes are treated as absent.

Parameters:

resource (PlannedResource)

Return type:

str | Mapping[str, Any] | None

raes_contracts.planning.planned_node_spec(resource)

Return spec.node for a provisioning node, otherwise None.

Parameters:

resource (PlannedResource)

Return type:

Mapping[str, Any] | None

raes_contracts.planning.planned_realization_authority(plan, address, requirement_kind)

Return one resolved authority entry, or None when not present.

Parameters:
Return type:

ResolvedRealizationAuthority | None

raes_contracts.planning.planned_resource_authored_name(resource)

Return the authored top-level resource name, if one is available.

Parameters:

resource (PlannedResource)

Return type:

str | None

raes_contracts.planning.planned_resource_name(resource)

Return the authored resource name or its full canonical address.

The address is a stable, provider-neutral fallback. Backends that require provider-safe native names remain responsible for deriving those names from the address.

Parameters:

resource (PlannedResource)

Return type:

str

raes_contracts.planning.planned_resource_payload(resource)

Return the resource’s mapping payload, or None when it is malformed.

The original mapping is returned without copying or mutation. This reader is domain-neutral; callers should use the narrower provisioning readers below for fields whose meaning depends on a runtime domain or resource type.

Parameters:

resource (PlannedResource)

Return type:

Mapping[str, Any] | None

raes_contracts.planning.require_plan_operation_identity(domain, address, resource_type)

Reject operations outside a plan endpoint’s closed identity domain.

Parameters:
Return type:

None

Runtime state

Shared runtime state and control-plane result contracts.

class raes_contracts.runtime_state.ApplyResult

Bases: object

Result of applying or starting a runtime plan.

success: bool
snapshot: RuntimeSnapshot
diagnostics: list[Diagnostic]
changed_addresses: list[str]
details: dict[str, Any]
operational_realization_observations: tuple[RealizationObservationDisclosure, ...] = ()
materialization_attestation: MaterializationSubmission | None = None
__init__(success, snapshot, diagnostics=<factory>, changed_addresses=<factory>, details=<factory>, operational_realization_observations=(), materialization_attestation=None)
Parameters:
Return type:

None

class raes_contracts.runtime_state.OperationAdmissionContext

Bases: ContractModel

Immutable, value-free authority and request context fixed at admission.

model_config = {'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

actor_id: _ContextString
authorization_scope: tuple[_ContextString, ...]
target_scope: _ContextString
run_scope: _ContextString
operation_kind: OperationKind
request_commitment: _RequestCommitment
parent_operation_id: _ContextString | None
class raes_contracts.runtime_state.OperationKind

Bases: str, Enum

Closed kinds of work admitted by the runtime control plane.

PROVISIONING = 'provisioning'
ORCHESTRATION = 'orchestration'
EVALUATION = 'evaluation'
WORKFLOW_CANCELLATION = 'workflow-cancellation'
WORKFLOW_TIMEOUT_RECONCILIATION = 'workflow-timeout-reconciliation'
PARTICIPANT_ACTION = 'participant-action'
PARTICIPANT_CONTROL = 'participant-control'
PARTICIPANT_CROSSING = 'participant-crossing'
COMPOSITION_PHASE = 'composition-phase'
INDETERMINATE_RESOLUTION = 'indeterminate-resolution'
__new__(value)
class raes_contracts.runtime_state.OperationReceipt

Bases: object

Portable acknowledgment for an accepted control-plane operation.

operation_id: str
domain: RuntimeDomain
submitted_at: str
accepted: bool
context: OperationAdmissionContext
schema_version: str = 'runtime-operation/v1'
diagnostics: list[Diagnostic]
__init__(operation_id, domain, submitted_at, accepted, context, schema_version='runtime-operation/v1', diagnostics=<factory>)
Parameters:
Return type:

None

class raes_contracts.runtime_state.OperationState

Bases: str, Enum

Lifecycle for async control-plane operations.

ACCEPTED = 'accepted'
RUNNING = 'running'
SUCCEEDED = 'succeeded'
FAILED = 'failed'
CANCELLED = 'cancelled'
INDETERMINATE = 'indeterminate'
__new__(value)
class raes_contracts.runtime_state.OperationStatus

Bases: object

Portable status for a submitted control-plane operation.

operation_id: str
domain: RuntimeDomain
state: OperationState
submitted_at: str
updated_at: str
context: OperationAdmissionContext
schema_version: str = 'runtime-operation/v1'
diagnostics: list[Diagnostic]
changed_addresses: list[str]
__init__(operation_id, domain, state, submitted_at, updated_at, context, schema_version='runtime-operation/v1', diagnostics=<factory>, changed_addresses=<factory>)
Parameters:
Return type:

None

class raes_contracts.runtime_state.RealizationObservationDisclosure

Bases: object

Corroboration metadata for one realized inventory concern.

Most concern disclosures remain value-free. compute-substrate is a deliberately non-sensitive governed exception: its independently observed mechanism is needed to distinguish authored demand from actual selection.

address: str
field_path: str
domain: str
requirement_kind: str
verification_scope: RealizationVerificationScope
observation_strength: ObservationStrength
observed_value: str | None = None
operating_system: ObservedOperatingSystemIdentity | None = None
operation_id: str | None = None
envelope_digest: str | None = None
configuration_digest: str | None = None
observer_version: str | None = None
sequence: int | None = None
binding_verified: bool = False
__init__(address, field_path, domain, requirement_kind, verification_scope, observation_strength, observed_value=None, operating_system=None, operation_id=None, envelope_digest=None, configuration_digest=None, observer_version=None, sequence=None, binding_verified=False)
Parameters:
  • address (str)

  • field_path (str)

  • domain (str)

  • requirement_kind (str)

  • verification_scope (RealizationVerificationScope)

  • observation_strength (ObservationStrength)

  • observed_value (str | None)

  • operating_system (ObservedOperatingSystemIdentity | None)

  • operation_id (str | None)

  • envelope_digest (str | None)

  • configuration_digest (str | None)

  • observer_version (str | None)

  • sequence (int | None)

  • binding_verified (bool)

Return type:

None

class raes_contracts.runtime_state.RealizationProvenanceEntry

Bases: object

SEM-218 provenance for one realized realization concern (invariant I5).

Records, for a single realization concern that entered a runtime snapshot / result / history surface, its SEM-218 explicitness class and the origin of the realized value: author-declared (honoured exactly as the author wrote it), processor-derived (produced by deterministic processor activity), or backend-realized (picked by the backend from an open or constrained surface admitted by I3). It carries field-path and kind references only — never the realized value itself, which may carry sensitive material (SEM-218 host-exposure gate).

address: str
field_path: str
domain: str
requirement_kind: str
explicitness: _ExplicitnessClass
provenance: _ExplicitnessProvenance
governing_scope: str | None = None
artifact_satisfaction: ArtifactSatisfactionDisclosureModel | None = None
__init__(address, field_path, domain, requirement_kind, explicitness, provenance, governing_scope=None, artifact_satisfaction=None)
Parameters:
  • address (str)

  • field_path (str)

  • domain (str)

  • requirement_kind (str)

  • explicitness (_ExplicitnessClass)

  • provenance (_ExplicitnessProvenance)

  • governing_scope (str | None)

  • artifact_satisfaction (ArtifactSatisfactionDisclosureModel | None)

Return type:

None

class raes_contracts.runtime_state.RuntimeSnapshot

Bases: object

Current runtime snapshot.

entries: dict[str, SnapshotEntry]
orchestration_results: dict[str, dict[str, Any]]
orchestration_history: dict[str, list[dict[str, Any]]]
evaluation_results: dict[str, dict[str, Any]]
evaluation_history: dict[str, list[dict[str, Any]]]
proposition_truth_results: dict[str, dict[str, Any]]
participant_episode_results: dict[str, dict[str, Any]]
participant_episode_history: dict[str, list[dict[str, Any]]]
participant_episode_closure_records: dict[str, list[dict[str, Any]]]
participant_behavior_history: dict[str, list[dict[str, Any]]]
participant_control_history: dict[str, list[dict[str, Any]]]
participant_crossing_history: dict[str, list[dict[str, Any]]]
participant_control_evaluation_history: dict[str, list[dict[str, Any]]]
mixed_composition_states: dict[str, dict[str, Any]]
mixed_composition_history: dict[str, list[dict[str, Any]]]
information_state_history: dict[str, list[dict[str, Any]]]
participant_outcome_history: dict[str, list[dict[str, Any]]]
participant_autonomous_execution_states: dict[str, dict[str, Any]]
participant_execution_services: dict[str, dict[str, Any]]
participant_resource_budget_states: dict[str, dict[str, Any]]
participant_resource_pool_states: dict[str, dict[str, Any]]
participant_resource_budget_events: dict[str, dict[str, Any]]
shared_state_records: dict[str, dict[str, Any]]
shared_state_history: dict[str, list[dict[str, Any]]]
joint_action_records: dict[str, dict[str, Any]]
time_management_contexts: dict[str, dict[str, Any]]
time_model_state: TimeRuntimeStateModel | None = None
realization_provenance: tuple[RealizationProvenanceEntry, ...] = ()
realization_observations: tuple[RealizationObservationDisclosure, ...] = ()
materialization_attestations: tuple[MaterializationArchiveRecord, ...] = ()
realization_envelope: RealizationEnvelopeIdentityModel | None = None
metadata: dict[str, Any]
get(address)
Parameters:

address (str)

Return type:

SnapshotEntry | None

for_domain(domain)
Parameters:

domain (RuntimeDomain)

Return type:

dict[str, SnapshotEntry]

with_entries(entries, **updates)
Parameters:
Return type:

RuntimeSnapshot

__init__(entries=<factory>, orchestration_results=<factory>, orchestration_history=<factory>, evaluation_results=<factory>, evaluation_history=<factory>, proposition_truth_results=<factory>, participant_episode_results=<factory>, participant_episode_history=<factory>, participant_episode_closure_records=<factory>, participant_behavior_history=<factory>, participant_control_history=<factory>, participant_crossing_history=<factory>, participant_control_evaluation_history=<factory>, mixed_composition_states=<factory>, mixed_composition_history=<factory>, information_state_history=<factory>, participant_outcome_history=<factory>, participant_autonomous_execution_states=<factory>, participant_execution_services=<factory>, participant_resource_budget_states=<factory>, participant_resource_pool_states=<factory>, participant_resource_budget_events=<factory>, shared_state_records=<factory>, shared_state_history=<factory>, joint_action_records=<factory>, time_management_contexts=<factory>, time_model_state=None, realization_provenance=(), realization_observations=(), materialization_attestations=(), realization_envelope=None, metadata=<factory>)
Parameters:
  • entries (dict[str, SnapshotEntry])

  • orchestration_results (dict[str, dict[str, Any]])

  • orchestration_history (dict[str, list[dict[str, Any]]])

  • evaluation_results (dict[str, dict[str, Any]])

  • evaluation_history (dict[str, list[dict[str, Any]]])

  • proposition_truth_results (dict[str, dict[str, Any]])

  • participant_episode_results (dict[str, dict[str, Any]])

  • participant_episode_history (dict[str, list[dict[str, Any]]])

  • participant_episode_closure_records (dict[str, list[dict[str, Any]]])

  • participant_behavior_history (dict[str, list[dict[str, Any]]])

  • participant_control_history (dict[str, list[dict[str, Any]]])

  • participant_crossing_history (dict[str, list[dict[str, Any]]])

  • participant_control_evaluation_history (dict[str, list[dict[str, Any]]])

  • mixed_composition_states (dict[str, dict[str, Any]])

  • mixed_composition_history (dict[str, list[dict[str, Any]]])

  • information_state_history (dict[str, list[dict[str, Any]]])

  • participant_outcome_history (dict[str, list[dict[str, Any]]])

  • participant_autonomous_execution_states (dict[str, dict[str, Any]])

  • participant_execution_services (dict[str, dict[str, Any]])

  • participant_resource_budget_states (dict[str, dict[str, Any]])

  • participant_resource_pool_states (dict[str, dict[str, Any]])

  • participant_resource_budget_events (dict[str, dict[str, Any]])

  • shared_state_records (dict[str, dict[str, Any]])

  • shared_state_history (dict[str, list[dict[str, Any]]])

  • joint_action_records (dict[str, dict[str, Any]])

  • time_management_contexts (dict[str, dict[str, Any]])

  • time_model_state (TimeRuntimeStateModel | None)

  • realization_provenance (tuple[RealizationProvenanceEntry, ...])

  • realization_observations (tuple[RealizationObservationDisclosure, ...])

  • materialization_attestations (tuple[MaterializationArchiveRecord, ...])

  • realization_envelope (RealizationEnvelopeIdentityModel | None)

  • metadata (dict[str, Any])

Return type:

None

class raes_contracts.runtime_state.RuntimeSnapshotEnvelope

Bases: object

Portable envelope around the current runtime snapshot.

schema_version: str = 'runtime-snapshot/v1'
snapshot: RuntimeSnapshot
__init__(schema_version='runtime-snapshot/v1', snapshot=<factory>)
Parameters:
Return type:

None

class raes_contracts.runtime_state.SnapshotEntry

Bases: object

Recorded runtime state for a single canonical resource.

address: str
domain: RuntimeDomain
resource_type: str
payload: dict[str, Any]
ordering_dependencies: tuple[str, ...] = ()
refresh_dependencies: tuple[str, ...] = ()
status: str = 'ready'
profile_bindings: tuple[DomainProfileBindingModel, ...] = ()
__init__(address, domain, resource_type, payload, ordering_dependencies=(), refresh_dependencies=(), status='ready', profile_bindings=())
Parameters:
  • address (str)

  • domain (RuntimeDomain)

  • resource_type (str)

  • payload (dict[str, Any])

  • ordering_dependencies (tuple[str, ...])

  • refresh_dependencies (tuple[str, ...])

  • status (str)

  • profile_bindings (tuple[DomainProfileBindingModel, ...])

Return type:

None

raes_contracts.runtime_state.is_operation_transition_allowed(source, target)

Return whether the closed ADR-104 persisted transition is legal.

Parameters:
Return type:

bool

raes_contracts.runtime_state.operation_terminal_diagnostic(state)

Return the stable diagnostic for a non-success terminal classification.

Parameters:

state (OperationState)

Return type:

Diagnostic

raes_contracts.runtime_state.operation_terminal_diagnostics(state, diagnostics)

Return diagnostics with exactly one canonical terminal classification.

Parameters:
Return type:

list[Diagnostic]

raes_contracts.runtime_state.operation_transition_diagnostic(source, target)

Return the stable value-free diagnostic for an illegal transition.

Parameters:
Return type:

Diagnostic

raes_contracts.runtime_state.validate_changed_addresses(addresses)
Parameters:

addresses (list[str])

Return type:

None

Workflow results

Shared workflow runtime result contracts.

class raes_contracts.workflow.WorkflowCancellationRequest

Bases: object

Portable request for cancelling one workflow run.

workflow_address: str
run_id: str | None = None
reason: str = 'cancelled by operator'
__init__(workflow_address, run_id=None, reason='cancelled by operator')
Parameters:
  • workflow_address (str)

  • run_id (str | None)

  • reason (str)

Return type:

None

class raes_contracts.workflow.WorkflowCompensationStatus

Bases: str, Enum

Portable workflow compensation status.

NOT_REQUIRED = 'not_required'
PENDING = 'pending'
RUNNING = 'running'
SUCCEEDED = 'succeeded'
FAILED = 'failed'
__new__(value)
class raes_contracts.workflow.WorkflowExecutionContract

Bases: object

Compiled contract for validating workflow-level execution state/history.

state_schema_version: str = 'workflow-step-state/v1'
start_step: str = ''
timeout_seconds: int | None = None
steps: dict[str, WorkflowStepSemanticContract]
step_types: dict[str, str]
control_edges: dict[str, tuple[str, ...]]
join_owners: dict[str, str]
call_steps: dict[str, str]
compensation_mode: str = 'disabled'
compensation_triggers: tuple[str, ...] = ()
compensation_targets: dict[str, str]
compensation_ordering: str = 'reverse_completion'
compensation_failure_policy: str = 'fail_workflow'
observable_steps: tuple[str, ...] = ()
classmethod from_mapping(payload)
Parameters:

payload (Mapping[str, Any])

Return type:

WorkflowExecutionContract

__init__(state_schema_version='workflow-step-state/v1', start_step='', timeout_seconds=None, steps=<factory>, step_types=<factory>, control_edges=<factory>, join_owners=<factory>, call_steps=<factory>, compensation_mode='disabled', compensation_triggers=(), compensation_targets=<factory>, compensation_ordering='reverse_completion', compensation_failure_policy='fail_workflow', observable_steps=())
Parameters:
  • state_schema_version (str)

  • start_step (str)

  • timeout_seconds (int | None)

  • steps (dict[str, WorkflowStepSemanticContract])

  • step_types (dict[str, str])

  • control_edges (dict[str, tuple[str, ...]])

  • join_owners (dict[str, str])

  • call_steps (dict[str, str])

  • compensation_mode (str)

  • compensation_triggers (tuple[str, ...])

  • compensation_targets (dict[str, str])

  • compensation_ordering (str)

  • compensation_failure_policy (str)

  • observable_steps (tuple[str, ...])

Return type:

None

class raes_contracts.workflow.WorkflowExecutionState

Bases: object

Internal normalized workflow result envelope.

state_schema_version: str = 'workflow-step-state/v1'
workflow_status: WorkflowStatus = 'pending'
run_id: str = ''
started_at: str = ''
updated_at: str = ''
terminal_reason: str | None = None
compensation_status: WorkflowCompensationStatus = 'not_required'
compensation_started_at: str | None = None
compensation_updated_at: str | None = None
compensation_failures: list[dict[str, Any]]
steps: dict[str, WorkflowStepExecutionState]
classmethod from_payload(payload)
Parameters:

payload (Mapping[str, Any])

Return type:

WorkflowExecutionState

to_payload()
Return type:

dict[str, Any]

__init__(state_schema_version='workflow-step-state/v1', workflow_status=WorkflowStatus.PENDING, run_id='', started_at='', updated_at='', terminal_reason=None, compensation_status=WorkflowCompensationStatus.NOT_REQUIRED, compensation_started_at=None, compensation_updated_at=None, compensation_failures=<factory>, steps=<factory>)
Parameters:
  • state_schema_version (str)

  • workflow_status (WorkflowStatus)

  • run_id (str)

  • started_at (str)

  • updated_at (str)

  • terminal_reason (str | None)

  • compensation_status (WorkflowCompensationStatus)

  • compensation_started_at (str | None)

  • compensation_updated_at (str | None)

  • compensation_failures (list[dict[str, Any]])

  • steps (dict[str, WorkflowStepExecutionState])

Return type:

None

class raes_contracts.workflow.WorkflowHistoryEvent

Bases: object

Internal normalized workflow history event.

event_type: WorkflowHistoryEventType
timestamp: str
step_name: str | None = None
branch_name: str | None = None
join_step: str | None = None
outcome: WorkflowStepOutcome | None = None
details: dict[str, Any]
invocation_id: str | None = None
dispatch_id: str | None = None
attempt: int | None = None
origin: str | None = None
classmethod from_payload(payload)
Parameters:

payload (Mapping[str, Any])

Return type:

WorkflowHistoryEvent

to_payload()
Return type:

dict[str, Any]

__init__(event_type, timestamp, step_name=None, branch_name=None, join_step=None, outcome=None, details=<factory>, invocation_id=None, dispatch_id=None, attempt=None, origin=None)
Parameters:
  • event_type (WorkflowHistoryEventType)

  • timestamp (str)

  • step_name (str | None)

  • branch_name (str | None)

  • join_step (str | None)

  • outcome (WorkflowStepOutcome | None)

  • details (dict[str, Any])

  • invocation_id (str | None)

  • dispatch_id (str | None)

  • attempt (int | None)

  • origin (str | None)

Return type:

None

class raes_contracts.workflow.WorkflowHistoryEventType

Bases: str, Enum

Portable workflow history event kinds.

WORKFLOW_STARTED = 'workflow_started'
STEP_STARTED = 'step_started'
STEP_COMPLETED = 'step_completed'
STEP_REPORTED = 'step_reported'
SWITCH_CASE_SELECTED = 'switch_case_selected'
CALL_STARTED = 'call_started'
CALL_COMPLETED = 'call_completed'
BRANCH_ENTERED = 'branch_entered'
BRANCH_CONVERGED = 'branch_converged'
WORKFLOW_COMPLETED = 'workflow_completed'
WORKFLOW_FAILED = 'workflow_failed'
WORKFLOW_CANCELLED = 'workflow_cancelled'
WORKFLOW_TIMED_OUT = 'workflow_timed_out'
COMPENSATION_REGISTERED = 'compensation_registered'
COMPENSATION_STARTED = 'compensation_started'
COMPENSATION_WORKFLOW_STARTED = 'compensation_workflow_started'
COMPENSATION_WORKFLOW_COMPLETED = 'compensation_workflow_completed'
COMPENSATION_WORKFLOW_FAILED = 'compensation_workflow_failed'
COMPENSATION_COMPLETED = 'compensation_completed'
COMPENSATION_FAILED = 'compensation_failed'
__new__(value)
class raes_contracts.workflow.WorkflowResultContract

Bases: object

Compiled contract for validating portable workflow result envelopes.

state_schema_version: str = 'workflow-step-state/v1'
observable_steps: dict[str, WorkflowStepSemanticContract]
classmethod from_mapping(payload)
Parameters:

payload (Mapping[str, Any])

Return type:

WorkflowResultContract

__init__(state_schema_version='workflow-step-state/v1', observable_steps=<factory>)
Parameters:
Return type:

None

class raes_contracts.workflow.WorkflowStatus

Bases: str, Enum

Portable workflow-level execution status.

PENDING = 'pending'
RUNNING = 'running'
SUCCEEDED = 'succeeded'
FAILED = 'failed'
CANCELLED = 'cancelled'
TIMED_OUT = 'timed_out'
__new__(value)
class raes_contracts.workflow.WorkflowStepExecutionState

Bases: object

Internal normalized execution state for one workflow-visible step.

lifecycle: WorkflowStepLifecycle = 'pending'
outcome: WorkflowStepOutcome | None = None
attempts: int = 0
attempt_provenance: tuple[WorkflowStepAttemptProvenance, ...] = ()
classmethod from_payload(payload)
Parameters:

payload (Mapping[str, Any])

Return type:

WorkflowStepExecutionState

to_payload()
Return type:

dict[str, Any]

__init__(lifecycle=WorkflowStepLifecycle.PENDING, outcome=None, attempts=0, attempt_provenance=())
Parameters:
Return type:

None

class raes_contracts.workflow.WorkflowStepAttemptProvenance

Bases: object

Portable provenance for one governed workflow-step realization attempt.

step_name: str
execution_mode: str
attempt_id: str
objective_address: str = ''
procedure_ref: str = ''
exposed_scaffold_refs: tuple[str, ...] = ()
allowed_action_families: tuple[str, ...] = ()
selected_action_family: str = ''
selected_tool_ref: str = ''
selected_affordance_ref: str = ''
fact_versions: tuple[str, ...] = ()
outcome: str = ''
evidence_refs: tuple[str, ...] = ()
assertion_truth_refs: tuple[str, ...] = ()
participant_report: str = ''
classmethod from_payload(payload)
Parameters:

payload (Mapping[str, Any])

Return type:

WorkflowStepAttemptProvenance

to_payload()
Return type:

dict[str, Any]

__init__(step_name, execution_mode, attempt_id, objective_address='', procedure_ref='', exposed_scaffold_refs=(), allowed_action_families=(), selected_action_family='', selected_tool_ref='', selected_affordance_ref='', fact_versions=(), outcome='', evidence_refs=(), assertion_truth_refs=(), participant_report='')
Parameters:
  • step_name (str)

  • execution_mode (str)

  • attempt_id (str)

  • objective_address (str)

  • procedure_ref (str)

  • exposed_scaffold_refs (tuple[str, ...])

  • allowed_action_families (tuple[str, ...])

  • selected_action_family (str)

  • selected_tool_ref (str)

  • selected_affordance_ref (str)

  • fact_versions (tuple[str, ...])

  • outcome (str)

  • evidence_refs (tuple[str, ...])

  • assertion_truth_refs (tuple[str, ...])

  • participant_report (str)

Return type:

None

class raes_contracts.workflow.WorkflowStepLifecycle

Bases: str, Enum

Portable execution lifecycle for workflow-visible step state.

PENDING = 'pending'
RUNNING = 'running'
COMPLETED = 'completed'
__new__(value)
class raes_contracts.workflow.WorkflowStepOutcome

Bases: str, Enum

Portable execution outcomes for workflow-visible step state.

SUCCEEDED = 'succeeded'
FAILED = 'failed'
EXHAUSTED = 'exhausted'
__new__(value)
raes_contracts.workflow.validate_workflow_step_result_contract(contract, *, lifecycle, outcome, attempts)

Validate a backend-reported workflow step result against a compiled contract.

Parameters:
Return type:

tuple[str, …]

Evaluation results

Shared evaluation runtime result contracts.

class raes_contracts.evaluation.EvaluationExecutionContract

Bases: object

Compiled contract for validating evaluator history/state transitions.

state_schema_version: str = 'evaluation-result-state/v1'
resource_type: str = ''
allowed_statuses: tuple[str, ...] = ('pending', 'running', 'ready', 'failed')
history_event_types: tuple[str, ...] = ('evaluation_started', 'evaluation_updated', 'evaluation_ready', 'evaluation_failed')
requires_start_event: bool = True
classmethod from_mapping(payload)
Parameters:

payload (Mapping[str, Any])

Return type:

EvaluationExecutionContract

__init__(state_schema_version='evaluation-result-state/v1', resource_type='', allowed_statuses=('pending', 'running', 'ready', 'failed'), history_event_types=('evaluation_started', 'evaluation_updated', 'evaluation_ready', 'evaluation_failed'), requires_start_event=True)
Parameters:
  • state_schema_version (str)

  • resource_type (str)

  • allowed_statuses (tuple[str, ...])

  • history_event_types (tuple[str, ...])

  • requires_start_event (bool)

Return type:

None

class raes_contracts.evaluation.EvaluationExecutionState

Bases: object

Internal normalized execution state for one evaluator-observable resource.

state_schema_version: str = 'evaluation-result-state/v1'
resource_type: str = ''
run_id: str = ''
status: EvaluationResultStatus = 'pending'
observed_at: str = ''
updated_at: str = ''
passed: bool | None = None
score: float | int | None = None
max_score: int | None = None
detail: str | None = None
evidence_refs: tuple[str, ...] = ()
classmethod from_payload(payload)
Parameters:

payload (Mapping[str, Any])

Return type:

EvaluationExecutionState

to_payload()
Return type:

dict[str, Any]

__init__(state_schema_version='evaluation-result-state/v1', resource_type='', run_id='', status=EvaluationResultStatus.PENDING, observed_at='', updated_at='', passed=None, score=None, max_score=None, detail=None, evidence_refs=())
Parameters:
  • state_schema_version (str)

  • resource_type (str)

  • run_id (str)

  • status (EvaluationResultStatus)

  • observed_at (str)

  • updated_at (str)

  • passed (bool | None)

  • score (float | int | None)

  • max_score (int | None)

  • detail (str | None)

  • evidence_refs (tuple[str, ...])

Return type:

None

class raes_contracts.evaluation.EvaluationHistoryEvent

Bases: object

Internal normalized evaluator history event.

event_type: EvaluationHistoryEventType
timestamp: str
status: EvaluationResultStatus
passed: bool | None = None
score: float | int | None = None
max_score: int | None = None
detail: str | None = None
evidence_refs: tuple[str, ...] = ()
details: dict[str, Any]
classmethod from_payload(payload)
Parameters:

payload (Mapping[str, Any])

Return type:

EvaluationHistoryEvent

to_payload()
Return type:

dict[str, Any]

__init__(event_type, timestamp, status, passed=None, score=None, max_score=None, detail=None, evidence_refs=(), details=<factory>)
Parameters:
Return type:

None

class raes_contracts.evaluation.EvaluationHistoryEventType

Bases: str, Enum

Portable evaluator history event kinds.

EVALUATION_STARTED = 'evaluation_started'
EVALUATION_UPDATED = 'evaluation_updated'
EVALUATION_READY = 'evaluation_ready'
EVALUATION_FAILED = 'evaluation_failed'
__new__(value)
class raes_contracts.evaluation.EvaluationResultContract

Bases: object

Compiled contract for validating evaluator result envelopes.

state_schema_version: str = 'evaluation-result-state/v1'
resource_type: str = ''
supports_passed: bool = False
supports_score: bool = False
fixed_max_score: int | None = None
classmethod from_mapping(payload)
Parameters:

payload (Mapping[str, Any])

Return type:

EvaluationResultContract

__init__(state_schema_version='evaluation-result-state/v1', resource_type='', supports_passed=False, supports_score=False, fixed_max_score=None)
Parameters:
  • state_schema_version (str)

  • resource_type (str)

  • supports_passed (bool)

  • supports_score (bool)

  • fixed_max_score (int | None)

Return type:

None

class raes_contracts.evaluation.EvaluationResultStatus

Bases: str, Enum

Portable lifecycle for evaluator-observable results.

PENDING = 'pending'
RUNNING = 'running'
READY = 'ready'
FAILED = 'failed'
__new__(value)
raes_contracts.evaluation.validate_evaluation_result(contract, state)

Return contract violations for one evaluator result envelope.

Parameters:
Return type:

list[str]

Participant episodes

Shared participant episode runtime contracts.

class raes_contracts.participant_episode.ParticipantEpisodeControlAction

Bases: str, Enum

INITIALIZE = 'initialize'
RESET = 'reset'
RESTART = 'restart'
__new__(value)
class raes_contracts.participant_episode.ParticipantEpisodeExecutionState

Bases: object

Internal normalized participant-episode execution state envelope.

state_schema_version: str = 'participant-episode-state/v1'
participant_address: str = ''
episode_id: str = ''
sequence_number: int = 0
status: ParticipantEpisodeStatus = 'initializing'
terminal_reason: ParticipantEpisodeTerminalReason | None = None
initialized_at: str = ''
updated_at: str = ''
terminated_at: str | None = None
last_control_action: ParticipantEpisodeControlAction = 'initialize'
previous_episode_id: str | None = None
classmethod from_payload(payload)
Parameters:

payload (Mapping[str, Any])

Return type:

ParticipantEpisodeExecutionState

to_payload()
Return type:

dict[str, Any]

__init__(state_schema_version='participant-episode-state/v1', participant_address='', episode_id='', sequence_number=0, status=ParticipantEpisodeStatus.INITIALIZING, terminal_reason=None, initialized_at='', updated_at='', terminated_at=None, last_control_action=ParticipantEpisodeControlAction.INITIALIZE, previous_episode_id=None)
Parameters:
Return type:

None

class raes_contracts.participant_episode.ParticipantEpisodeHistoryEvent

Bases: object

Internal normalized participant-episode history event.

event_type: ParticipantEpisodeHistoryEventType
timestamp: str
participant_address: str
episode_id: str
sequence_number: int
terminal_reason: ParticipantEpisodeTerminalReason | None = None
control_action: ParticipantEpisodeControlAction | None = None
details: dict[str, Any]
classmethod from_payload(payload)
Parameters:

payload (Mapping[str, Any])

Return type:

ParticipantEpisodeHistoryEvent

to_payload()
Return type:

dict[str, Any]

__init__(event_type, timestamp, participant_address, episode_id, sequence_number, terminal_reason=None, control_action=None, details=<factory>)
Parameters:
Return type:

None

class raes_contracts.participant_episode.ParticipantEpisodeHistoryEventType

Bases: str, Enum

EPISODE_INITIALIZED = 'episode_initialized'
EPISODE_RUNNING = 'episode_running'
EPISODE_COMPLETED = 'episode_completed'
EPISODE_TIMED_OUT = 'episode_timed_out'
EPISODE_TRUNCATED = 'episode_truncated'
EPISODE_INTERRUPTED = 'episode_interrupted'
EPISODE_RESET = 'episode_reset'
EPISODE_RESTARTED = 'episode_restarted'
__new__(value)
class raes_contracts.participant_episode.ParticipantEpisodeInitializeRequest

Bases: object

Portable request for initializing the first episode of a participant.

participant_address: str
episode_id: str | None = None
__init__(participant_address, episode_id=None)
Parameters:
  • participant_address (str)

  • episode_id (str | None)

Return type:

None

class raes_contracts.participant_episode.ParticipantEpisodeResetRequest

Bases: object

Portable request for resetting a non-terminal participant episode.

participant_address: str
episode_id: str | None = None
reason: str = 'reset by operator'
__init__(participant_address, episode_id=None, reason='reset by operator')
Parameters:
  • participant_address (str)

  • episode_id (str | None)

  • reason (str)

Return type:

None

class raes_contracts.participant_episode.ParticipantEpisodeRestartRequest

Bases: object

Portable request for restarting a terminated participant episode.

participant_address: str
episode_id: str | None = None
reason: str = 'restarted by operator'
__init__(participant_address, episode_id=None, reason='restarted by operator')
Parameters:
  • participant_address (str)

  • episode_id (str | None)

  • reason (str)

Return type:

None

class raes_contracts.participant_episode.ParticipantEpisodeStatus

Bases: str, Enum

INITIALIZING = 'initializing'
RUNNING = 'running'
TERMINATED = 'terminated'
__new__(value)
class raes_contracts.participant_episode.ParticipantEpisodeTerminalReason

Bases: str, Enum

COMPLETED = 'completed'
TIMED_OUT = 'timed_out'
TRUNCATED = 'truncated'
INTERRUPTED = 'interrupted'
__new__(value)
class raes_contracts.participant_episode.ParticipantEpisodeTerminateRequest

Bases: object

Portable request for driving the current episode to TERMINATED.

participant_address: str
terminal_reason: ParticipantEpisodeTerminalReason = 'interrupted'
detail: str = 'terminated by operator'
__init__(participant_address, terminal_reason=ParticipantEpisodeTerminalReason.INTERRUPTED, detail='terminated by operator')
Parameters:
Return type:

None

Participant implementation manifests

ParticipantImplementationManifestModel and ParticipantImplementationProvenanceModel live in raes_contracts.contracts with the other published contract models. The manifest names the implementation and its supported behavior, limits, and tool needs. The provenance record states which implementation, manifest, configuration, contract versions, and decision-surface policy a run used.

Mixed-backend execution and readback

Optional bindings and stage reports for one admitted mixed edge or native handoff, exchanged through the backend operation protocol below. They grant no authority, and the shared runtime does not read them.

Published executable bindings for admitted mixed-composition edges and handoffs.

One binding is the plain-data form of the installed bridge, time coordinator and readback services for exactly one admitted sem-234/rev1 directed edge or component-changing phase transition. It names pinned identities and the obligations they must honour, and each role has its own service. Decoding a binding installs nothing, selects no provider and grants no execution authority; trusted joins against the sealed profile live in raes_contracts.contracts.mixed_backend_validation.

class raes_contracts.contracts.mixed_backend_binding.MixedBackendEdgeBindingModel

Bases: OperationContractModel

Bridge, coordinator and readers for one admitted directed edge.

The destination provider executes the mapped action under one RAES participant-crossing operation; owning the effect confers no controller, disclosure or terminal-commit authority. Native translation stays inside the pinned bridge, so the compiled action subject is preserved. Each role is a distinct service, so the bridge never grants its own order or reads back its own delivery or observation.

kind: Literal['edge']
edge_id: OperationIdentifier
operation_kind: Literal[OperationKind.PARTICIPANT_CROSSING]
owner_component_id: OperationIdentifier
owner_allocation_id: OperationIdentifier
participant_address: CompiledAddress
audience_scope_ref: OperationIdentifier
source_action_address: CompiledAddress
destination_action_address: CompiledAddress
subject_transformation: Literal['compiled-identity']
bridge: MixedBackendServiceModel
time: MixedBackendEdgeTimeRequirementModel
mapping_loss: MixedCompositionMappingLossModel
delivery_reader: MixedBackendServiceModel
observation_reader: MixedBackendServiceModel | None
required_evidence_refs: _EvidenceRefs
model_config = {'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class raes_contracts.contracts.mixed_backend_binding.MixedBackendEdgeTimeRequirementModel

Bases: MixedBackendTimeRequirementModel

Edge time requirement that also carries the admitted edge’s temporal coupling.

temporal_coupling: Literal['tight', 'bounded-asynchronous', 'asynchronous']
model_config = {'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class raes_contracts.contracts.mixed_backend_binding.MixedBackendExecutionBindingModel

Bases: OperationContractModel

One installed executable binding, joined to its sealed profile by identity and digest.

schema_version: Literal[MIXED_BACKEND_EXECUTION_BINDING_SCHEMA_VERSION]
binding_id: OperationIdentifier
profile_id: OperationIdentifier
profile_revision: Literal[MIXED_COMPOSITION_PROFILE_REVISION]
profile_digest: PrefixedDigestString
subject: MixedBackendSubjectBinding
model_config = {'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class raes_contracts.contracts.mixed_backend_binding.MixedBackendHandoffBindingModel

Bases: OperationContractModel

Native responsibility transfer for one admitted component-changing transition.

The transfer service, coordinator and owner reader are distinct services, so a transfer never grants its own order or reads back its own owner.

kind: Literal['handoff']
transition_id: OperationIdentifier
operation_kind: Literal[OperationKind.COMPOSITION_PHASE]
source_component_id: OperationIdentifier
destination_component_id: OperationIdentifier
source_owner_ref: OperationIdentifier
destination_owner_ref: OperationIdentifier
transfer: MixedBackendServiceModel
time: MixedBackendTimeRequirementModel
owner_reader: MixedBackendServiceModel
required_evidence_refs: _EvidenceRefs
model_config = {'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class raes_contracts.contracts.mixed_backend_binding.MixedBackendServiceModel

Bases: OperationContractModel

Pinned installed implementation identity; never a module, path, URL or command.

service_ref: OperationIdentifier
version: OperationIdentifier
digest: OperationDigest
model_config = {'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class raes_contracts.contracts.mixed_backend_binding.MixedBackendTimeRequirementModel

Bases: OperationContractModel

Named clocks, mapping and governed order a coordinator must grant before invocation.

time_model_ref: OperationIdentifier
time_model_digest: PrefixedDigestString
source_clock_address: CompiledAddress
destination_clock_address: CompiledAddress
mapping_ref: CompiledAddress
ordering_basis: GovernedOrderingBasis
required_comparison: Literal['ordered']
coordinator: MixedBackendServiceModel
model_config = {'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

raes_contracts.contracts.mixed_backend_binding.mixed_backend_binding_reference(binding)

Return the content-bound command reference a shared operation request must carry.

Parameters:

binding (MixedBackendExecutionBindingModel)

Return type:

OperationArtifactReferenceModel

Correlated stage reports for one mixed-backend invocation, never terminal commits.

Each report proposes one fact for one shared backend operation invocation: a time grant, bridge execution, destination delivery, participant observation, native handoff or owner readback. Every stage names the pinned service that produced it. Execution, delivery and observation are separate stages, so one success flag cannot imply another; partial and unknown execution keep their own status. A reader must validate reports against the installed binding, the shared operation transcript and its own trusted readbacks; only RAES may commit operation state, composition history and terminal outcomes.

class raes_contracts.contracts.mixed_backend_stages.MixedBackendDeliveryStageModel

Bases: OperationContractModel

Destination receipt read back by the pinned delivery reader, not the bridge.

stage: Literal['delivery']
producer: MixedBackendServiceModel
destination_component_id: OperationIdentifier
receipt_ref: OperationIdentifier
evidence_refs: _RequiredRefs
model_config = {'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class raes_contracts.contracts.mixed_backend_stages.MixedBackendExecutionStageModel

Bases: OperationContractModel

Bridge execution readback; it establishes no delivery or participant observation.

stage: Literal['execution']
producer: MixedBackendServiceModel
source_action_address: CompiledAddress
destination_action_address: CompiledAddress
status: Literal['succeeded', 'failed', 'partial', 'unknown']
evidence_refs: _Refs
mapping_loss_refs: _Refs
cessation_evidence_refs: _Refs
model_config = {'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class raes_contracts.contracts.mixed_backend_stages.MixedBackendHandoffStageModel

Bases: OperationContractModel

Native transfer disposition at the exact predecessor history head and phase revision.

stage: Literal['handoff']
producer: MixedBackendServiceModel
status: Literal['committed', 'failed', 'pending', 'stale', 'unknown']
predecessor_history_head: OperationIdentifier
phase_revision: OperationCounter
order_ref: OperationIdentifier
evidence_refs: _Refs
model_config = {'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class raes_contracts.contracts.mixed_backend_stages.MixedBackendObservationStageModel

Bases: OperationContractModel

Participant and audience readback after delivery; delivery alone is not observation.

stage: Literal['observation']
producer: MixedBackendServiceModel
participant_address: CompiledAddress
audience_scope_ref: OperationIdentifier
observation_ref: OperationIdentifier
evidence_refs: _RequiredRefs
model_config = {'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class raes_contracts.contracts.mixed_backend_stages.MixedBackendOwnerReadbackStageModel

Bases: OperationContractModel

Native responsibility owner read back by the pinned owner reader after a transfer attempt.

stage: Literal['owner-readback']
producer: MixedBackendServiceModel
owner_component_id: OperationIdentifier
owner_ref: OperationIdentifier
phase_revision: OperationCounter
evidence_refs: _RequiredRefs
model_config = {'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class raes_contracts.contracts.mixed_backend_stages.MixedBackendStageReportModel

Bases: OperationContractModel

One stage fact bound to the exact shared operation invocation and request commitment.

The sequence is the stage’s fixed position in its chain: time grant 1, execution or handoff 2, delivery or owner readback 3, observation 4. Each producer numbers its own report without seeing the others, and a reader accepts the reports in ascending sequence.

schema_version: Literal[MIXED_BACKEND_STAGE_REPORT_SCHEMA_VERSION]
binding: BackendOperationBindingModel
request_digest: OperationDigest
sequence: OperationPositive
stage: MixedBackendStage
model_config = {'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class raes_contracts.contracts.mixed_backend_stages.MixedBackendTimeGrantStageModel

Bases: OperationContractModel

Coordinator grant at the committed clock coordinates; incomparable grants permit no invocation.

stage: Literal['time-grant']
producer: MixedBackendServiceModel
mapping_ref: CompiledAddress
ordering_basis: GovernedOrderingBasis
order_ref: OperationIdentifier
comparison: Literal['ordered', 'incomparable']
source_coordinate: TimeCoordinateModel
destination_coordinate: TimeCoordinateModel
mapping_evidence_refs: _RequiredRefs
timing_evidence_refs: _RequiredRefs
model_config = {'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

Trusted joins for mixed-backend bindings and their shared operation requests.

These pure validators compare the published carriers with trusted inputs resolved by the caller: the sealed composition profile and its resolution context, and the shared backend operation request, capabilities and admission response. They perform no I/O, dispatch or state mutation. Passing them proves neither backend truth nor runtime adoption.

raes_contracts.contracts.mixed_backend_validation.require_mixed_backend_admission(binding, request, capabilities, response)

Join shared contextual admission to one installed binding; grants no invocation authority.

Parameters:
Return type:

None

raes_contracts.contracts.mixed_backend_validation.require_mixed_backend_request(binding, request)

Require a shared request to commit to this exact binding, operation kind and installed service.

The request’s backend is the edge bridge or native transfer service the binding pins, so shared capabilities and admission answer for that service.

Parameters:
Return type:

None

raes_contracts.contracts.mixed_backend_validation.validate_mixed_backend_bindings(profile, context, bindings)

Require exactly one matching installed binding for each executable obligation.

Every edge active in an admitted phase needs a bridge binding, and every transition that changes the active components needs a one-to-one native handoff binding. Alternative profiles have no such obligation and admit no binding. Missing, foreign, duplicate or contradictory bindings and unsupported coordination refuse the whole set.

Parameters:
Return type:

None

Cross-message checks for the stage reports of one mixed-backend invocation.

The validator joins stage reports to their installed binding, the shared backend operation request and response transcript, and trusted inputs resolved by the caller: the time-model declaration with the reference and digest it was resolved under, the committed time readback the coordinator received, RAES’s own time readback after the invocation and, for a native handoff, the committed composition state. It performs no I/O, dispatch or state mutation, and passing it proves neither backend truth nor runtime adoption.

class raes_contracts.contracts.mixed_backend_transcript.MixedBackendStageContext

Bases: object

Trusted, caller-resolved inputs for one invocation’s stage reports; none comes from a backend.

time_model is the declaration that the caller resolved under time_model_ref and time_model_digest, which must equal the binding’s time requirement. time_state is the committed time readback that the coordinator received. post_time_state is RAES’s own time readback after the invocation, or None when none was taken. composition_state is the committed composition state of the invocation’s run and binding’s profile: it must activate a bound edge, or hold a handoff’s source component but not its destination. A native handoff requires it.

time_model: TimeModelDeclarationModel
time_model_ref: str
time_model_digest: str
time_state: TimeRuntimeStateModel
post_time_state: TimeRuntimeStateModel | None = None
composition_state: MixedCompositionRuntimeStateModel | None = None
__init__(time_model, time_model_ref, time_model_digest, time_state, post_time_state=None, composition_state=None)
Parameters:
  • time_model (TimeModelDeclarationModel)

  • time_model_ref (str)

  • time_model_digest (str)

  • time_state (TimeRuntimeStateModel)

  • post_time_state (TimeRuntimeStateModel | None)

  • composition_state (MixedCompositionRuntimeStateModel | None)

Return type:

None

raes_contracts.contracts.mixed_backend_transcript.established_mixed_backend_state(binding, request, responses, reports, *, context, controls=())

Return the state established by a validated transcript, without granting publication authority.

Parameters:
Return type:

OperationState

raes_contracts.contracts.mixed_backend_transcript.mixed_backend_time_comparison(required, time_model, source, destination)

Return the order that the admitted mapping proves, in exact rational arithmetic within one segment.

Parameters:
Return type:

Literal[‘ordered’, ‘incomparable’]

raes_contracts.contracts.mixed_backend_transcript.validate_mixed_backend_stage_reports(binding, request, responses, reports, *, context, controls=())

Validate one invocation’s stage reports against its binding, transcript and trusted context.

The trusted time model must be resolved under the binding’s time-model reference and digest, and a committed composition state must still activate the bound edge or precede the bound handoff. The grant’s coordinates must equal the committed time readback, and a native handoff must name the committed composition history head and phase revision. Each report’s sequence must be its stage’s fixed chain position (time grant 1, execution or handoff 2, delivery or owner readback 3, observation 4), and reports are accepted in ascending sequence whatever order they are supplied in. Each stage must follow its prerequisite and name the service pinned for its role, and the invocation stage needs an ordered grant and an accepted acknowledgement. A proposed success or known failure must equal the state that the stages and the trusted readbacks establish.

Parameters:
Return type:

None

Optional mixed-backend bridge, time-coordinator and stage-reader protocols.

RAE retains admission, authored order, terminal publication and recovery. These protocols let an installed service report correlated stage evidence for one admitted edge or native handoff through the shared backend operation protocol. Method presence never establishes capability, conformance or authority, and declaring the contracts is not effective support.

class raes_backend_protocols.mixed_backend.MixedBackendBridge

Bases: BackendOperationProvider, Protocol

Installed edge bridge or native transfer service for exactly one admitted binding.

The shared operation methods admit, start, observe, cancel and reconcile one invocation whose request commits to execution_binding(). Starting invokes the destination provider at most once, and a duplicate identity starts nothing. Stage reports are evidence proposals: a reader must validate them, and only RAE may commit the operation, composition history and terminal state.

execution_binding()

Return the installed binding declaration; it supplies no contextual willingness.

Return type:

MixedBackendExecutionBindingModel

stage_reports(control)

Return bounded execution or handoff stage reports for an independently authorized read.

Each report’s sequence is 2, the chain position of execution and handoff.

Parameters:

control (BackendOperationControlModel)

Return type:

tuple[MixedBackendStageReportModel, …]

class raes_backend_protocols.mixed_backend.MixedStageReader

Bases: Protocol

Read back destination delivery, participant observation or native owner state.

read_stage(control)

Return one stage report that names this reader as its producer; the read has no effects.

Its sequence is its stage’s chain position: 3 for delivery or owner readback, 4 for observation.

Parameters:

control (BackendOperationControlModel)

Return type:

MixedBackendStageReportModel

__init__(*args, **kwargs)
class raes_backend_protocols.mixed_backend.MixedTimeCoordinator

Bases: Protocol

Grant a governed order over the bound clocks before an invocation starts.

grant(request, time_state)

Return one time-grant report at the coordinates of time_state; it advances no clock.

Its sequence is 1, the time grant’s chain position.

Parameters:
Return type:

MixedBackendStageReportModel

__init__(*args, **kwargs)
raes_backend_protocols.mixed_backend.require_mixed_backend_service(service, role, declared_contracts)

Validate the opt-in declaration and installed call shapes without invoking code.

A bridge must also install the shared operation protocol. Behavioral conformance, the trusted profile join and contextual admission remain separate checks.

Parameters:
  • service (object)

  • role (Literal['bridge', 'coordinator', 'reader'])

  • declared_contracts (Iterable[str])

Return type:

None

Backend operation supervision

The optional backend protocol reports evidence for one admitted invocation. The shared runtime retains authorization, scenario execution and terminal state.

Bounded portable requests for one backend invocation, never execution authority.

class raes_contracts.contracts.backend_operation.OperationContractModel

Bases: ContractModel

Immutable bounded values; decoding a value supplies no authorization.

model_config = {'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class raes_contracts.contracts.backend_operation.OperationArtifactReferenceModel

Bases: OperationContractModel

Content-bound reference resolved through the owning admitted artifact authority.

contract_id: Annotated[str, Field(max_length=128, pattern='^[a-z0-9]+(?:-[a-z0-9]+)*-v[0-9]+$')]
artifact_id: OperationIdentifier
digest: OperationDigest
model_config = {'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class raes_contracts.contracts.backend_operation.OperationBudgetModel

Bases: OperationContractModel

Remaining apparatus budget; the origin is retained across duplicate delivery.

origin_id: OperationIdentifier
started_at: Annotated[Rfc3339DateTimeString, Field(max_length=64)]
limit_ms: OperationPositive
remaining_ms: OperationPositive
model_config = {'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class raes_contracts.contracts.backend_operation.OperationEffectScopeModel

Bases: OperationContractModel

Target/run exclusion is the default; narrowing needs admitted independence.

kind: Literal['target-run', 'resources']
addresses: tuple[CompiledAddress, ...]
independence: OperationArtifactReferenceModel | None
model_config = {'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class raes_contracts.contracts.backend_operation.BackendOperationBindingModel

Bases: OperationContractModel

Original context and invocation identity, including state-publication fences.

operation_id: OperationIdentifier
invocation_id: OperationIdentifier
attempt_id: OperationIdentifier
worker_id: OperationIdentifier
deployment_id: OperationIdentifier
owner_generation: OperationCounter
execution_generation: OperationCounter
backend_id: OperationIdentifier
baseline_revision: OperationIdentifier
context: OperationAdmissionContext
effect_scope: OperationEffectScopeModel
model_config = {'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class raes_contracts.contracts.backend_operation.BackendOperationRequestModel

Bases: OperationContractModel

Exact admitted command and requirements checked again immediately before dispatch.

schema_version: Literal[BACKEND_OPERATION_REQUEST_SCHEMA_VERSION]
binding: BackendOperationBindingModel
command: OperationArtifactReferenceModel
requirement_refs: tuple[OperationArtifactReferenceModel, ...]
required_guarantees: tuple[OperationGuarantee, ...]
budget: OperationBudgetModel
workflow_step: WorkflowStepDispatch | None
model_config = {'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class raes_contracts.contracts.backend_operation.BackendOperationCapabilitiesModel

Bases: OperationContractModel

Installed provider declaration; neither willingness nor a conformance proof.

execution_policy: ExecutionPolicyCapabilities | None
schema_version: Literal[BACKEND_OPERATION_CAPABILITIES_SCHEMA_VERSION]
backend_id: OperationIdentifier
revision: OperationDigest
supported_operation_kinds: tuple[OperationKind, ...]
guarantees: tuple[OperationGuarantee, ...]
model_config = {'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class raes_contracts.contracts.backend_operation.BackendOperationControlModel

Bases: OperationContractModel

Independently authorized, idempotent control/observation of the original invocation.

schema_version: Literal[BACKEND_OPERATION_CONTROL_SCHEMA_VERSION]
binding: BackendOperationBindingModel
request_digest: OperationDigest
control_id: OperationIdentifier
actor_id: OperationIdentifier
authorization_scope: tuple[OperationIdentifier, ...]
action: Literal['cancel', 'observe', 'reconcile']
budget: OperationBudgetModel
model_config = {'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

Backend reports are correlated evidence proposals, never runtime terminal commits.

class raes_contracts.contracts.backend_operation_response.BackendOperationAdmissionModel

Bases: OperationContractModel

kind: Literal['admission']
disposition: Literal['willing', 'refused']
capability_digest: OperationDigest
reason: OperationRefusalReason | None
model_config = {'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class raes_contracts.contracts.backend_operation_response.BackendOperationAcknowledgementModel

Bases: OperationContractModel

kind: Literal['acknowledgement']
disposition: Literal['accepted', 'refused']
reason: OperationRefusalReason | None
model_config = {'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class raes_contracts.contracts.backend_operation_response.BackendOperationProgressModel

Bases: OperationContractModel

kind: Literal['progress']
phase: Literal['queued', 'executing', 'settling']
evidence_refs: tuple[OperationArtifactReferenceModel, ...]
model_config = {'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class raes_contracts.contracts.backend_operation_response.BackendOperationControlDispositionModel

Bases: OperationContractModel

kind: Literal['control']
control_id: OperationIdentifier
control_digest: OperationDigest
disposition: Literal['recorded', 'accepted', 'refused', 'unsupported', 'already-terminal']
model_config = {'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class raes_contracts.contracts.backend_operation_response.BackendOperationEffectsModel

Bases: OperationContractModel

Effect knowledge and cessation are independent, scoped backend assertions.

effect: Literal['absent', 'complete', 'partial', 'unknown']
cessation_established: StrictBool
evidence_refs: tuple[OperationArtifactReferenceModel, ...]
residual_scope: tuple[CompiledAddress, ...]
residual_state: OperationArtifactReferenceModel | None
external_fence: OperationArtifactReferenceModel | None
model_config = {'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class raes_contracts.contracts.backend_operation_response.BackendOperationOutcomeModel

Bases: OperationContractModel

Proposed outcome requiring RAE’s native validation and atomic publication.

kind: Literal['outcome']
proposed_state: Literal[OperationState.SUCCEEDED, OperationState.FAILED, OperationState.CANCELLED, OperationState.INDETERMINATE]
effects: BackendOperationEffectsModel
satisfaction: Literal['satisfied', 'unsatisfied', 'unknown']
release_gates_satisfied: StrictBool
cancellation_established: StrictBool
result: OperationArtifactReferenceModel | None
model_config = {'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class raes_contracts.contracts.backend_operation_response.BackendOperationReconciliationModel

Bases: OperationContractModel

Observation for separately authorized resolution, with no replay instruction.

kind: Literal['reconciliation']
control_id: OperationIdentifier
control_digest: OperationDigest
effects: BackendOperationEffectsModel
model_config = {'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class raes_contracts.contracts.backend_operation_response.BackendOperationResponseModel

Bases: OperationContractModel

schema_version: Literal[BACKEND_OPERATION_RESPONSE_SCHEMA_VERSION]
binding: BackendOperationBindingModel
request_digest: OperationDigest
sequence: OperationPositive
message: BackendOperationMessage
model_config = {'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

Pure cross-message checks shared by transports and contract conformance readers.

raes_contracts.contracts.backend_operation_validation.backend_operation_request_digest(request)
Parameters:

request (BackendOperationRequestModel)

Return type:

str

raes_contracts.contracts.backend_operation_validation.backend_operation_control_digest(control)
Parameters:

control (BackendOperationControlModel)

Return type:

str

raes_contracts.contracts.backend_operation_validation.canonical_backend_operation_capabilities_digest(capabilities)
Parameters:

capabilities (BackendOperationCapabilitiesModel)

Return type:

str

raes_contracts.contracts.backend_operation_validation.validate_backend_operation_response(request, response, *, control=None)

Reject foreign or stale evidence; this does not authenticate its producer.

Parameters:
Return type:

None

raes_contracts.contracts.backend_operation_validation.require_backend_operation_admission(request, capabilities, response)

Check declarations and exact-context willingness, never grant invocation authority.

Parameters:
Return type:

None

raes_contracts.contracts.backend_operation_validation.require_backend_execution_policy_admission(request, capabilities, response, native_plan, *, resolved_native_plan_commitment=None)

Validate a native plan resolved by its owner, then exact-context willingness.

The caller authenticates and authorizes separately, resolves the artifact through its owning authority, and consumes the one-use effect claim. This pure validator supplies none of that authority and performs no recovery. A protected artifact owner may supply its freshly computed content commitment. It must never copy that proof from the untrusted request. Omitting it retains canonical native-plan SHA-256 validation.

Parameters:
Return type:

None

raes_contracts.contracts.backend_operation_validation.require_backend_plan_policy_capabilities(native_plan, capabilities)

Reuse the exact authored policy checks after a trusted owner resolves its command.

Parameters:
Return type:

None

raes_contracts.contracts.backend_operation_validation.validate_backend_operation_history(request, responses, *, controls=())

Validate a bounded invocation transcript; no scheduling, effects or state mutation.

Parameters:
Return type:

None

Optional one-invocation backend protocol; RAE retains scenario and state authority.

class raes_backend_protocols.operation_supervision.BackendOperationProvider

Bases: Protocol

Bounded calls on separately provisioned effect/control capacity.

All responses echo the exact invocation binding and request commitment. Callers authenticate and authorize separately, resolve the command and requirements through their owning authorities, and consume the current one-use invocation claim before start. No method schedules scenario work, allocates a trial/retry, publishes a snapshot or commits a terminal state. A caller timeout cannot establish that any remote effects have stopped.

operation_capabilities()

Return the installed declaration; it supplies no contextual willingness.

Return type:

BackendOperationCapabilitiesModel

check_operation(request)

Return admission/refusal without effects; recheck immediately before dispatch.

Parameters:

request (BackendOperationRequestModel)

Return type:

BackendOperationResponseModel

start_operation(request)

Return acknowledgement; duplicate identity never starts another effect.

A refusal establishes that this invocation did not start. Once effects are possible, report uncertainty/outcome evidence through observation.

Parameters:

request (BackendOperationRequestModel)

Return type:

BackendOperationResponseModel

observe_operation(request)

Return one progress, outcome, reconciliation or control-disposition record.

Reads are bounded and independently authorized. An observation with effects of its own requires separate effect admission, not this method.

Parameters:

request (BackendOperationControlModel)

Return type:

BackendOperationResponseModel

cancel_operation(request)

Return control disposition; acceptance is not cessation or rollback.

Parameters:

request (BackendOperationControlModel)

Return type:

BackendOperationResponseModel

reconcile_operation(request)

Return read-only reconciliation evidence or an explicit control refusal.

Parameters:

request (BackendOperationControlModel)

Return type:

BackendOperationResponseModel

__init__(*args, **kwargs)
raes_backend_protocols.operation_supervision.require_inject_occurrence_provider(provider, declared_contracts)

Require the inject occurrence/outcome opt-in on an installed operation provider.

ADR-112 inject execution reuses the one-invocation protocol: the command is the claimed inject-occurrence-v1 and readback is inject-occurrence-outcome-v1. Inject-binding support or plan start is not this declaration, and passing this shape check proves no willingness, effect or conformance.

Parameters:
  • provider (object)

  • declared_contracts (Iterable[str])

Return type:

BackendOperationProvider

raes_backend_protocols.operation_supervision.require_operation_provider(provider, declared_contracts)

Validate opt-in declaration and installed call shapes without invoking code.

This public protocol boundary cannot import the runtime’s private registry checker. It provides the same signature binding for independent embedders; behavioral conformance and contextual admission remain separate checks.

Parameters:
  • provider (object)

  • declared_contracts (Iterable[str])

Return type:

BackendOperationProvider

External inject triggers, occurrences and readback

Draft ADR-112 carriers for an external inject request, its claimed occurrence, per-binding readback and participant correlation. They grant no trigger authority and do not execute an inject.

ADR-112 inject trigger requests and claimed occurrences; neither executes an effect.

class raes_contracts.contracts.inject_occurrence.InjectTargetBindingModel

Bases: OperationContractModel

One selected realization instance of a compiled node binding; entity names never select hosts.

binding: CompiledAddress
node: CompiledAddress
instance: OperationIdentifier
revision: OperationIdentifier
model_config = {'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class raes_contracts.contracts.inject_occurrence.InjectIndependentPlacementModel

Bases: OperationContractModel

Direct request through an admitted independent binding; no schedule is invented.

kind: Literal['independent']
model_config = {'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class raes_contracts.contracts.inject_occurrence.InjectEventPlacementModel

Bases: OperationContractModel

Event-anchored request; the event’s precondition assertions remain binding.

kind: Literal['event']
event: CompiledAddress
model_config = {'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class raes_contracts.contracts.inject_occurrence.InjectSchedulePlacementModel

Bases: OperationContractModel

One uniquely identified schedule slot, claimable at most once in its run.

kind: Literal['schedule']
event: CompiledAddress
script: CompiledAddress
story: CompiledAddress | None
slot: OperationIdentifier
model_config = {'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class raes_contracts.contracts.inject_occurrence.InjectTriggerRequestModel

Bases: OperationContractModel

A caller’s selection within admitted intent; acceptance is not an effect.

schema_version: Literal[INJECT_TRIGGER_REQUEST_SCHEMA_VERSION]
request_key: OperationIdentifier
occurrence_id: OperationIdentifier
target_scope: OperationIdentifier
run_scope: OperationIdentifier
plan: OperationArtifactReferenceModel
inject: CompiledAddress
bindings: tuple[InjectTargetBindingModel, ...]
placement: InjectPlacement
input_ref: OperationArtifactReferenceModel | None
expected_head: OperationIdentifier
model_config = {'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class raes_contracts.contracts.inject_occurrence.InjectOrderModel

Bases: OperationContractModel

Trusted ordering-authority token; neither arrival order nor a clock tick.

scope: OperationIdentifier
predecessor: OperationIdentifier
position: OperationPositive
model_config = {'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class raes_contracts.contracts.inject_occurrence.InjectOccurrenceModel

Bases: OperationContractModel

Atomic claim of one occurrence under exact admitted pins; not dispatch or outcome.

schema_version: Literal[INJECT_OCCURRENCE_SCHEMA_VERSION]
operation_id: OperationIdentifier
request: InjectTriggerRequestModel
admission: OperationAdmissionContext
admission_evidence: tuple[OperationArtifactReferenceModel, ...]
store_revision: OperationIdentifier
order: InjectOrderModel
scenario: OperationArtifactReferenceModel
source: OperationArtifactReferenceModel
realization: OperationArtifactReferenceModel
evidence_requirements: tuple[OperationArtifactReferenceModel, ...]
model_config = {'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

raes_contracts.contracts.inject_occurrence.inject_trigger_request_digest(request)
Parameters:

request (InjectTriggerRequestModel)

Return type:

str

raes_contracts.contracts.inject_occurrence.inject_occurrence_digest(occurrence)
Parameters:

occurrence (InjectOccurrenceModel)

Return type:

str

raes_contracts.contracts.inject_occurrence.inject_retry_key(occurrence)

Return the ADR-104 scoped retry identity: actor, operation kind and client key.

Parameters:

occurrence (InjectOccurrenceModel)

Return type:

tuple[str, str, str]

raes_contracts.contracts.inject_occurrence.require_inject_trigger_retry(occurrence, request, *, actor_id)

Return the original claim for an exact retry; never admit, rebase or dispatch again.

Callers authorize receipt access before any lookup, so a conflict reveals no other actor’s claim. Changed content under the same key is a conflict.

Parameters:
Return type:

InjectOccurrenceModel

raes_contracts.contracts.inject_occurrence.validate_inject_occurrence_claims(occurrences)

Reject reuse of a retry key, occurrence, operation, schedule slot, order position or predecessor.

Two claims that follow one head fork the run’s order. Head tokens are opaque, so this cannot check that a predecessor is the head that the preceding claim produced.

Parameters:

occurrences (Sequence[InjectOccurrenceModel])

Return type:

None

ADR-112 inject invocation, per-binding readback and participant correlation; an adopting runtime settles.

class raes_contracts.contracts.inject_occurrence_outcome.InjectBindingOutcomeModel

Bases: OperationContractModel

One selected binding’s reported effect knowledge; a missing report is never absence.

binding: InjectTargetBindingModel
effects: BackendOperationEffectsModel
readback: OperationArtifactReferenceModel | None
model_config = {'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

raes_contracts.contracts.inject_occurrence_outcome.inject_occurrence_effect(bindings)

Aggregate fan-out facts (EI-04); any unknown or unceased binding stays indeterminate.

Parameters:

bindings (tuple[InjectBindingOutcomeModel, ...])

Return type:

Literal[‘effect-applied’, ‘effect-absent’, ‘known-partial’, ‘indeterminate’]

class raes_contracts.contracts.inject_occurrence_outcome.InjectOccurrenceOutcomeModel

Bases: OperationContractModel

Per-binding readback for one claimed occurrence; not delivery, observation or a commit.

schema_version: Literal[INJECT_OCCURRENCE_OUTCOME_SCHEMA_VERSION]
occurrence: OperationArtifactReferenceModel
response: BackendOperationResponseModel
bindings: tuple[InjectBindingOutcomeModel, ...]
effect: InjectOccurrenceEffect
model_config = {'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class raes_contracts.contracts.inject_occurrence_outcome.InjectOccurrenceCorrelationModel

Bases: OperationContractModel

Exact applied occurrence, settled outcome and produced result a participant consumer joins.

schema_version: Literal[INJECT_OCCURRENCE_CORRELATION_SCHEMA_VERSION]
occurrence: OperationArtifactReferenceModel
outcome: OperationArtifactReferenceModel
result: OperationArtifactReferenceModel
model_config = {'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

raes_contracts.contracts.inject_occurrence_outcome.inject_occurrence_reference(occurrence)

Return the content-bound command reference for one claimed occurrence.

Parameters:

occurrence (InjectOccurrenceModel)

Return type:

OperationArtifactReferenceModel

raes_contracts.contracts.inject_occurrence_outcome.inject_occurrence_outcome_digest(outcome)
Parameters:

outcome (InjectOccurrenceOutcomeModel)

Return type:

str

raes_contracts.contracts.inject_occurrence_outcome.require_inject_occurrence_invocation(occurrence, request)

Bind one backend invocation to the exact claimed occurrence; this grants no dispatch.

Parameters:
Return type:

None

raes_contracts.contracts.inject_occurrence_outcome.validate_inject_occurrence_outcome(occurrence, request, outcome)

Join readback to the exact occurrence and invocation; an adopting runtime still validates and commits.

Parameters:
Return type:

None

raes_contracts.contracts.inject_occurrence_outcome.inject_occurrence_correlation(occurrence, request, outcome)

Return the participant join; only a successful applied effect supplies a produced result.

Parameters:
Return type:

InjectOccurrenceCorrelationModel

raes_contracts.contracts.inject_occurrence_outcome.validate_inject_occurrence_correlation(occurrence, request, outcome, correlation)

Accept a received participant join only if it equals the join recomputed from its sources.

Parameters:
Return type:

None

Workflow step dispatch

The runtime sends one command and accepts one bound response. The backend does not receive successor authority.

Closed single-step commands; graph transitions remain runtime authority.

class raes_contracts.contracts.workflow_dispatch.WorkflowStatePredicate

Bases: ContractModel

step_name: NonEmptyString
outcomes: tuple[Literal['succeeded', 'failed', 'exhausted'], ...]
min_attempts: Annotated[int, Field(strict=True, ge=1)] | None
model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class raes_contracts.contracts.workflow_dispatch.WorkflowPredicate

Bases: ContractModel

assertion_addresses: tuple[NonEmptyString, ...]
objective_addresses: tuple[NonEmptyString, ...]
step_state_predicates: tuple[WorkflowStatePredicate, ...]
model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class raes_contracts.contracts.workflow_dispatch.WorkflowCase

Bases: ContractModel

case_index: Annotated[int, Field(strict=True, ge=0)]
predicate: WorkflowPredicate
next_step: NonEmptyString
model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class raes_contracts.contracts.workflow_dispatch.WorkflowExecutionInputs

Bases: ContractModel

execution_mode: Literal['scripted', 'objective', 'scaffolded']
objective_address: str
procedure_ref: str
scaffold_refs: tuple[NonEmptyString, ...]
allowed_action_families: tuple[NonEmptyString, ...]
tool_affordance_refs: tuple[NonEmptyString, ...]
capability_refs: tuple[NonEmptyString, ...]
fact_binding_refs: tuple[NonEmptyString, ...]
model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class raes_contracts.contracts.workflow_dispatch.WorkflowProgramStep

Bases: WorkflowExecutionInputs

name: NonEmptyString
step_type: StepKind
predicate: WorkflowPredicate | None
next_step: str
on_success: str
on_failure: str
on_exhausted: str
then_step: str
else_step: str
switch_cases: tuple[WorkflowCase, ...]
default_step: str
branches: tuple[NonEmptyString, ...]
join_step: str
owning_parallel_step: str
called_workflow_address: str
compensation_workflow_address: str
max_attempts: Annotated[int, Field(strict=True, ge=1)] | None
state_contract: dict[str, object]
model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class raes_contracts.contracts.workflow_dispatch.WorkflowProgram

Bases: ContractModel

Typed executable projection of an admitted compiled workflow.

workflow_address: NonEmptyString
start_step: NonEmptyString
steps: dict[NonEmptyString, WorkflowProgramStep]
timeout_seconds: Annotated[int, Field(strict=True, ge=1)] | None
compensation_mode: Literal['disabled', 'automatic']
compensation_triggers: tuple[Literal['failed', 'cancelled', 'timed_out'], ...]
compensation_failure_policy: Literal['fail_workflow', 'record_and_continue']
execution_policies: tuple[EffectiveExecutionPolicy, ...]
valid_references()
Return type:

Self

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class raes_contracts.contracts.workflow_dispatch.WorkflowStepDispatch

Bases: WorkflowExecutionInputs

model_config = {'extra': 'forbid', 'frozen': True, 'revalidate_instances': 'always'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

schema_version: Literal['workflow-step-dispatch/v1']
dispatch_id: NonEmptyString
program_digest: Sha256DigestString
root_operation_id: NonEmptyString
invocation_id: NonEmptyString
workflow_address: NonEmptyString
branch_id: NonEmptyString
step_name: NonEmptyString
step_type: StepKind
attempt: Attempt
predecessor_revision: Annotated[int, Field(strict=True, ge=0)]
observation_addresses: tuple[NonEmptyString, ...]
observation_digests: dict[NonEmptyString, Sha256DigestString]
execution_policy: EffectiveExecutionPolicy | None
execution_policy_scopes: tuple[EffectiveExecutionPolicy, ...]
remaining_budget_ms: Annotated[int, Field(strict=True, ge=0)] | None
property digest: str
class raes_contracts.contracts.workflow_dispatch.WorkflowStepResponse

Bases: ContractModel

model_config = {'extra': 'forbid', 'frozen': True, 'revalidate_instances': 'always'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

schema_version: Literal['workflow-step-response/v1']
dispatch_id: NonEmptyString
dispatch_digest: Sha256DigestString
outcome: Literal['succeeded', 'failed'] | None
observations: dict[NonEmptyString, Sha256DigestString]
attempt_provenance: WorkflowStepAttemptProvenanceModel | None
require_dispatch(dispatch)
Parameters:

dispatch (WorkflowStepDispatch)

Return type:

None