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:
objectStructured planner/runtime message.
- code: str¶
- domain: str¶
- address: str¶
- message: str¶
- property is_error: bool¶
- class raes_contracts.diagnostics.DiagnosticModel¶
Bases:
BaseModelClosed 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¶
- class raes_contracts.diagnostics.Severity¶
Bases:
str,EnumDiagnostic 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:
- 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].
- 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:
ContractModelDeterministic 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)¶
Planning¶
Native planning carriers; safe accessors return None for missing or inapplicable surfaces without validating.
- class raes_contracts.planning.ChangeAction¶
Bases:
str,EnumPlanner reconciliation result for a resource.
- CREATE = 'create'¶
- UPDATE = 'update'¶
- DELETE = 'delete'¶
- UNCHANGED = 'unchanged'¶
- __new__(value)¶
- class raes_contracts.planning.EvaluationOp¶
Bases:
PlanOperationEvaluation reconciliation operation.
- class raes_contracts.planning.EvaluationPlan¶
Bases:
objectResolved 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:
PlanOperationOrchestration reconciliation operation.
- class raes_contracts.planning.OrchestrationPlan¶
Bases:
objectResolved 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:
objectA 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:
objectIdentity of the realization a plan is computed for.
target_nameselects the backend target the plan is reconciled against, whilerun_idnames the authoritative run scope (run:<id>authority) andinstantiation_idnames 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:
objectNormalized 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:
PlanOperationProvisioning 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:
objectProvisioning 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:
objectOne 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,EnumResolved author permission for one portable realization concern.
- CLOSED = 'closed'¶
- OPEN = 'open'¶
- CONSTRAINED = 'constrained'¶
- EXACT = 'exact'¶
- __new__(value)¶
- class raes_contracts.planning.RealizationPreparationAuthority¶
Bases:
ContractModelConditional 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,EnumCanonical 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:
objectPortable, value-safe author boundary for one planned concern.
- address: str¶
- field_path: str¶
- domain: str¶
- requirement_kind: str¶
- payload_pointer: str¶
- 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,EnumTop-level runtime concern.
- PROVISIONING = 'provisioning'¶
- ORCHESTRATION = 'orchestration'¶
- EVALUATION = 'evaluation'¶
- PARTICIPANT = 'participant'¶
- __new__(value)¶
- raes_contracts.planning.planned_infrastructure_spec(resource)¶
Return
spec.infrastructurefor 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.nodefor a provisioning node, otherwiseNone.- 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
Nonewhen not present.- Parameters:
plan (ProvisioningPlan)
address (str)
requirement_kind (str)
- 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
Nonewhen 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:
domain (RuntimeDomain)
address (object)
resource_type (object)
- Return type:
None
Runtime state¶
Shared runtime state and control-plane result contracts.
- class raes_contracts.runtime_state.ApplyResult¶
Bases:
objectResult 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:
success (bool)
snapshot (RuntimeSnapshot)
diagnostics (list[Diagnostic])
changed_addresses (list[str])
details (dict[str, Any])
operational_realization_observations (tuple[RealizationObservationDisclosure, ...])
materialization_attestation (MaterializationSubmission | None)
- Return type:
None
- class raes_contracts.runtime_state.OperationAdmissionContext¶
Bases:
ContractModelImmutable, 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,EnumClosed 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:
objectPortable 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:
operation_id (str)
domain (RuntimeDomain)
submitted_at (str)
accepted (bool)
context (OperationAdmissionContext)
schema_version (str)
diagnostics (list[Diagnostic])
- Return type:
None
- class raes_contracts.runtime_state.OperationState¶
Bases:
str,EnumLifecycle 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:
objectPortable 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:
operation_id (str)
domain (RuntimeDomain)
state (OperationState)
submitted_at (str)
updated_at (str)
context (OperationAdmissionContext)
schema_version (str)
diagnostics (list[Diagnostic])
changed_addresses (list[str])
- Return type:
None
- class raes_contracts.runtime_state.RealizationObservationDisclosure¶
Bases:
objectCorroboration metadata for one realized inventory concern.
Most concern disclosures remain value-free.
compute-substrateis 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:
objectSEM-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), orbackend-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:
objectCurrent 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:
entries (dict[str, SnapshotEntry])
updates (object)
- Return type:
- __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:
objectPortable envelope around the current runtime snapshot.
- schema_version: str = 'runtime-snapshot/v1'¶
- snapshot: RuntimeSnapshot¶
- __init__(schema_version='runtime-snapshot/v1', snapshot=<factory>)¶
- Parameters:
schema_version (str)
snapshot (RuntimeSnapshot)
- Return type:
None
- class raes_contracts.runtime_state.SnapshotEntry¶
Bases:
objectRecorded 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:
source (OperationState)
target (OperationState)
- 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:
- raes_contracts.runtime_state.operation_terminal_diagnostics(state, diagnostics)¶
Return diagnostics with exactly one canonical terminal classification.
- Parameters:
state (OperationState)
diagnostics (list[Diagnostic])
- Return type:
list[Diagnostic]
- raes_contracts.runtime_state.operation_transition_diagnostic(source, target)¶
Return the stable value-free diagnostic for an illegal transition.
- Parameters:
source (OperationState)
target (OperationState)
- Return type:
- 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:
objectPortable 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,EnumPortable workflow compensation status.
- NOT_REQUIRED = 'not_required'¶
- PENDING = 'pending'¶
- RUNNING = 'running'¶
- SUCCEEDED = 'succeeded'¶
- FAILED = 'failed'¶
- __new__(value)¶
- class raes_contracts.workflow.WorkflowExecutionContract¶
Bases:
objectCompiled 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:
- __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:
objectInternal 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:
- 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:
objectInternal 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:
- 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,EnumPortable 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:
objectCompiled 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:
- __init__(state_schema_version='workflow-step-state/v1', observable_steps=<factory>)¶
- Parameters:
state_schema_version (str)
observable_steps (dict[str, WorkflowStepSemanticContract])
- Return type:
None
- class raes_contracts.workflow.WorkflowStatus¶
Bases:
str,EnumPortable 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:
objectInternal 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:
- to_payload()¶
- Return type:
dict[str, Any]
- __init__(lifecycle=WorkflowStepLifecycle.PENDING, outcome=None, attempts=0, attempt_provenance=())¶
- Parameters:
lifecycle (WorkflowStepLifecycle)
outcome (WorkflowStepOutcome | None)
attempts (int)
attempt_provenance (tuple[WorkflowStepAttemptProvenance, ...])
- Return type:
None
- class raes_contracts.workflow.WorkflowStepAttemptProvenance¶
Bases:
objectPortable 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:
- 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,EnumPortable execution lifecycle for workflow-visible step state.
- PENDING = 'pending'¶
- RUNNING = 'running'¶
- COMPLETED = 'completed'¶
- __new__(value)¶
- class raes_contracts.workflow.WorkflowStepOutcome¶
Bases:
str,EnumPortable 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:
contract (WorkflowStepSemanticContract)
lifecycle (str)
outcome (str | None)
attempts (int)
- Return type:
tuple[str, …]
Evaluation results¶
Shared evaluation runtime result contracts.
- class raes_contracts.evaluation.EvaluationExecutionContract¶
Bases:
objectCompiled 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:
- __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:
objectInternal 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:
- 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:
objectInternal 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:
- 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:
event_type (EvaluationHistoryEventType)
timestamp (str)
status (EvaluationResultStatus)
passed (bool | None)
score (float | int | None)
max_score (int | None)
detail (str | None)
evidence_refs (tuple[str, ...])
details (dict[str, Any])
- Return type:
None
- class raes_contracts.evaluation.EvaluationHistoryEventType¶
Bases:
str,EnumPortable 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:
objectCompiled 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:
- __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,EnumPortable 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:
contract (EvaluationResultContract)
state (EvaluationExecutionState)
- 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:
objectInternal 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:
- 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:
state_schema_version (str)
participant_address (str)
episode_id (str)
sequence_number (int)
status (ParticipantEpisodeStatus)
terminal_reason (ParticipantEpisodeTerminalReason | None)
initialized_at (str)
updated_at (str)
terminated_at (str | None)
last_control_action (ParticipantEpisodeControlAction)
previous_episode_id (str | None)
- Return type:
None
- class raes_contracts.participant_episode.ParticipantEpisodeHistoryEvent¶
Bases:
objectInternal 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:
- 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:
event_type (ParticipantEpisodeHistoryEventType)
timestamp (str)
participant_address (str)
episode_id (str)
sequence_number (int)
terminal_reason (ParticipantEpisodeTerminalReason | None)
control_action (ParticipantEpisodeControlAction | None)
details (dict[str, Any])
- 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:
objectPortable 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:
objectPortable 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:
objectPortable 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:
objectPortable 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:
participant_address (str)
terminal_reason (ParticipantEpisodeTerminalReason)
detail (str)
- 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:
OperationContractModelBridge, 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¶
- 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:
MixedBackendTimeRequirementModelEdge 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:
OperationContractModelOne 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:
OperationContractModelNative 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¶
- 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:
OperationContractModelPinned 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:
OperationContractModelNamed 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:
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:
OperationContractModelDestination 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:
OperationContractModelBridge 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:
OperationContractModelNative 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:
OperationContractModelParticipant 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:
OperationContractModelNative 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:
OperationContractModelOne 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:
OperationContractModelCoordinator 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:
binding (MixedBackendExecutionBindingModel)
request (BackendOperationRequestModel)
capabilities (BackendOperationCapabilitiesModel)
response (BackendOperationResponseModel)
- 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:
binding (MixedBackendExecutionBindingModel)
request (BackendOperationRequestModel)
- 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:
profile (MixedParticipantCompositionProfileModel)
context (MixedCompositionResolutionContext)
bindings (Sequence[MixedBackendExecutionBindingModel])
- 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:
objectTrusted, caller-resolved inputs for one invocation’s stage reports; none comes from a backend.
time_modelis the declaration that the caller resolved undertime_model_refandtime_model_digest, which must equal the binding’s time requirement.time_stateis the committed time readback that the coordinator received.post_time_stateis RAES’s own time readback after the invocation, orNonewhen none was taken.composition_stateis 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:
binding (MixedBackendExecutionBindingModel)
request (BackendOperationRequestModel)
responses (Sequence[BackendOperationResponseModel])
reports (Sequence[MixedBackendStageReportModel])
context (MixedBackendStageContext)
controls (Sequence[BackendOperationControlModel])
- Return type:
- 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:
required (MixedBackendTimeRequirementModel)
time_model (TimeModelDeclarationModel)
source (TimeCoordinateModel)
destination (TimeCoordinateModel)
- 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
sequencemust 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 ascendingsequencewhatever 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:
binding (MixedBackendExecutionBindingModel)
request (BackendOperationRequestModel)
responses (Sequence[BackendOperationResponseModel])
reports (Sequence[MixedBackendStageReportModel])
context (MixedBackendStageContext)
controls (Sequence[BackendOperationControlModel])
- 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,ProtocolInstalled 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:
- 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:
ProtocolRead 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:
- __init__(*args, **kwargs)¶
- class raes_backend_protocols.mixed_backend.MixedTimeCoordinator¶
Bases:
ProtocolGrant 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:
request (BackendOperationRequestModel)
time_state (TimeRuntimeStateModel)
- Return type:
- __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:
ContractModelImmutable 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:
OperationContractModelContent-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:
OperationContractModelRemaining 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:
OperationContractModelTarget/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:
OperationContractModelOriginal 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:
OperationContractModelExact 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:
OperationContractModelInstalled 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:
OperationContractModelIndependently 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:
OperationContractModelEffect 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:
OperationContractModelProposed 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:
OperationContractModelObservation 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:
request (BackendOperationRequestModel)
response (BackendOperationResponseModel)
control (BackendOperationControlModel | None)
- 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:
request (BackendOperationRequestModel)
capabilities (BackendOperationCapabilitiesModel)
response (BackendOperationResponseModel)
- 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:
request (BackendOperationRequestModel)
capabilities (BackendOperationCapabilitiesModel)
response (BackendOperationResponseModel)
native_plan (ProvisioningPlan | OrchestrationPlan | EvaluationPlan | WorkflowStepDispatch)
resolved_native_plan_commitment (str | None)
- 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:
native_plan (ProvisioningPlan | OrchestrationPlan | EvaluationPlan | WorkflowStepDispatch)
capabilities (BackendOperationCapabilitiesModel)
- 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:
request (BackendOperationRequestModel)
responses (Sequence[BackendOperationResponseModel])
controls (Sequence[BackendOperationControlModel])
- Return type:
None
Optional one-invocation backend protocol; RAE retains scenario and state authority.
- class raes_backend_protocols.operation_supervision.BackendOperationProvider¶
Bases:
ProtocolBounded 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:
- check_operation(request)¶
Return admission/refusal without effects; recheck immediately before dispatch.
- Parameters:
request (BackendOperationRequestModel)
- Return type:
- 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:
- 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:
- cancel_operation(request)¶
Return control disposition; acceptance is not cessation or rollback.
- Parameters:
request (BackendOperationControlModel)
- Return type:
- reconcile_operation(request)¶
Return read-only reconciliation evidence or an explicit control refusal.
- Parameters:
request (BackendOperationControlModel)
- Return type:
- __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-v1and readback isinject-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:
- 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:
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:
OperationContractModelOne 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:
OperationContractModelDirect 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:
OperationContractModelEvent-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:
OperationContractModelOne 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:
OperationContractModelA 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¶
- 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:
OperationContractModelTrusted 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:
OperationContractModelAtomic 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:
occurrence (InjectOccurrenceModel)
request (InjectTriggerRequestModel)
actor_id (str)
- Return type:
- 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:
OperationContractModelOne 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:
OperationContractModelPer-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:
OperationContractModelExact 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:
- 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:
occurrence (InjectOccurrenceModel)
request (BackendOperationRequestModel)
- 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:
occurrence (InjectOccurrenceModel)
request (BackendOperationRequestModel)
outcome (InjectOccurrenceOutcomeModel)
- 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:
occurrence (InjectOccurrenceModel)
request (BackendOperationRequestModel)
outcome (InjectOccurrenceOutcomeModel)
- Return type:
- 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:
occurrence (InjectOccurrenceModel)
request (BackendOperationRequestModel)
outcome (InjectOccurrenceOutcomeModel)
correlation (InjectOccurrenceCorrelationModel)
- 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:
ContractModelTyped 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