Runtime Layer¶

The raes_runtime package owns live runtime control: runtime targets, backend registry integration, manager lifecycle execution, control-plane submission and observation, operation persistence, security, and backend result-contract validation helpers.

Runtime APIs consume neutral DTOs from raes_contracts at backend and control-plane boundaries. Header-based control-plane identity is disabled by default and requires an explicit ControlPlaneSecurityConfig with trust_proxy_identity_headers=True.

Public API¶

Live runtime control surfaces for RAES SDL.

class raes_runtime.BackendRegistry¶

Bases: object

Registry of runtime target descriptors.

__init__()¶

Return type:: None

register(name, manifest_factory, components_factory)¶

Parameters:

name (str)
manifest_factory (Callable[[...], BackendManifest])
components_factory (Callable[[...], RuntimeTargetComponents])

Return type:

None

describe(name)¶

Parameters:: name (str)
Return type:: RuntimeTargetDescriptor

manifest(name, **config)¶

Parameters:

name (str)
config (Any)

Return type:

BackendManifest

create(name, **config)¶

Parameters:

name (str)
config (Any)

Return type:

RuntimeTarget

list_backends()¶

Return type:: list[str]

is_registered(name)¶

Parameters:: name (str)
Return type:: bool

class raes_runtime.RuntimeControlPlane¶

Bases: RuntimeLifecycleMixin, RuntimePlanAuthorizationMixin, RuntimeDurabilityMixin, RuntimeAdmissionMixin, WorkflowControlMixin, ParticipantControlMixin, ParticipantRetrievalMixin

Reference control plane for async runtime submission and observation.

__init__(target, *, initial_snapshot=None, store=None, behavior_specifications=None, crossing_policy_resolver=None, information_state_context_resolver=None, enforce_final_sink_flow_control=True)¶

Parameters:

target (_RuntimeTarget)
initial_snapshot (RuntimeSnapshot | None)
store (ControlPlaneStore | None)
behavior_specifications (Mapping[str, ParticipantBehaviorSpecificationRuntime] | None)
crossing_policy_resolver (ParticipantCrossingPolicyResolver | None)
information_state_context_resolver (ParticipantInformationStateContextResolver | None)
enforce_final_sink_flow_control (bool)

Return type:

None

property snapshot: RuntimeSnapshot¶

property target_name: str¶

audit_log()¶

Return type:: list[AuditEvent]

operational_apparatus_summary()¶

Return a compact operational view over existing control-plane carriers.

Return type:: dict[str, object]

submit_provisioning(plan, *, base_snapshot=None, idempotency_key='', request_fingerprint='', identity=None)¶

Parameters:

plan (ProvisioningPlan)
base_snapshot (RuntimeSnapshot | None)
idempotency_key (str)
request_fingerprint (str)
identity (object | None)

Return type:

OperationReceipt

submit_orchestration(plan, *, base_snapshot=None, idempotency_key='', request_fingerprint='', identity=None)¶

Parameters:

plan (OrchestrationPlan)
base_snapshot (RuntimeSnapshot | None)
idempotency_key (str)
request_fingerprint (str)
identity (object | None)

Return type:

OperationReceipt

submit_evaluation(plan, *, base_snapshot=None, idempotency_key='', request_fingerprint='', identity=None)¶

Parameters:

plan (EvaluationPlan)
base_snapshot (RuntimeSnapshot | None)
idempotency_key (str)
request_fingerprint (str)
identity (object | None)

Return type:

OperationReceipt

get_operation(operation_id)¶

Parameters:: operation_id (str)
Return type:: OperationStatus | None

observation_execution(operation_id)¶

Return committed metadata and explicitly retained descriptions.

Parameters:: operation_id (str)
Return type:: ObservationExecution | None

get_snapshot()¶

Return type:: RuntimeSnapshotEnvelope

class raes_runtime.RuntimeFactActionDisposition¶

Bases: str, Enum

Aggregate action-dispatch outcome across all compiled sinks.

BOUND = 'bound'¶

BLOCKED = 'blocked'¶

FAILED = 'failed'¶

INAPPLICABLE = 'inapplicable'¶

__new__(value)¶

class raes_runtime.RuntimeFactBindingAdmission¶

Bases: object

Trusted control-plane authorization for one action instance.

run_id: str¶

participant_address: str¶

episode_id: str¶

workflow_address: str | None¶

action_instance_id: str¶

action_contract_address: str¶

requested_at: str¶

authority_refs: frozenset[str]¶

selections: tuple[RuntimeFactBindingSelectionModel, ...]¶

property action_key: tuple[str, str, str, str | None, str, str]¶: Return the exact admitted action context.

__init__(run_id, participant_address, episode_id, workflow_address, action_instance_id, action_contract_address, requested_at, authority_refs, selections)¶

Parameters:

run_id (str)
participant_address (str)
episode_id (str)
workflow_address (str | None)
action_instance_id (str)
action_contract_address (str)
requested_at (str)
authority_refs (frozenset[str])
selections (tuple[RuntimeFactBindingSelectionModel, ...])

Return type:

None

class raes_runtime.RuntimeFactBindingPlane¶

Bases: object

Append-only fact plane whose dispatch policy comes from trusted admission.

__init__(*, admissions=(), action_dispatcher=None, supported_source_kinds=None)¶

Parameters:

admissions (Iterable[RuntimeFactBindingAdmission])
action_dispatcher (Callable[[RuntimeFactDispatchCommand], None] | None)
supported_source_kinds (Iterable[RuntimeFactSourceKind] | None)

Return type:

None

declare(declaration)¶

Parameters:: declaration (RuntimeFactDeclarationModel)
Return type:: None

append(version)¶

Parameters:: version (RuntimeFactVersionModel)
Return type:: None

history(fact_id)¶

Parameters:: fact_id (str)
Return type:: tuple[RuntimeFactVersionModel, …]

bind_action_inputs(request)¶

Parameters:: request (RuntimeFactBindingRequestModel)
Return type:: RuntimeFactBindingResult

binding_history()¶

Return type:: tuple[RuntimeFactBindingEventModel, …]

project_for_participant(*, run_id, participant_address, episode_id)¶

Parameters:

run_id (str)
participant_address (str)
episode_id (str)

Return type:

tuple[RuntimeFactProjectionModel, …]

project_for_workflow(*, run_id, workflow_address)¶

Parameters:

run_id (str)
workflow_address (str)

Return type:

tuple[RuntimeFactProjectionModel, …]

class raes_runtime.RuntimeFactBindingResult¶

Bases: object

Value-free portable outcome and binding evidence.

accepted: bool¶

action_disposition: RuntimeFactActionDisposition¶

events: tuple[RuntimeFactBindingEventModel, ...]¶

diagnostics: tuple[Diagnostic, ...]¶

__init__(accepted, action_disposition, events, diagnostics)¶

Parameters:

accepted (bool)
action_disposition (RuntimeFactActionDisposition)
events (tuple[RuntimeFactBindingEventModel, ...])
diagnostics (tuple[Diagnostic, ...])

Return type:

None

class raes_runtime.RuntimeFactDispatchCommand¶

Bases: object

One-shot command delivered only to the trusted action dispatcher.

__init__(bindings)¶

Parameters:: bindings (tuple[_RuntimeFactDispatchBinding, ...])
Return type:: None

property completed: bool¶: Report whether the trusted adapter consumed the command.

dispatch(*, send, secret_resolver=None)¶

Resolve protected references and synchronously deliver action inputs.

Parameters:

send (Callable[[Mapping[str, object]], None])
secret_resolver (Callable[[str], object] | None)

Return type:

None

class raes_runtime.RuntimeManager¶

Bases: _DestroyPhaseMixin, RuntimeParticipantExecutionMixin, RuntimeTimeControlMixin

Plans and executes SDL runtime work against a target.

__init__(target, *, initial_snapshot=None, stochastic_controls=(), information_state_context_resolver=None)¶

Parameters:

target (_RuntimeTarget)
initial_snapshot (RuntimeSnapshot | None)
stochastic_controls (Iterable[ExperimentStochasticControlModel])
information_state_context_resolver (ParticipantInformationStateContextResolver | None)

Return type:

None

property snapshot: RuntimeSnapshot¶

plan(scenario, snapshot=None, *, parameters=None, profile=None, artifact_availability=None, profile_authority=None, run_scope=None)¶

Parameters:

scenario (object)
snapshot (RuntimeSnapshot | None)
parameters (dict[str, object] | None)
profile (str | None)
artifact_availability (ArtifactAvailabilityContext | None)
profile_authority (PlanProfileAuthority | None)
run_scope (PlanScope | None)

Return type:

ExecutionPlan

apply(execution_plan)¶

Parameters:: execution_plan (ExecutionPlan)
Return type:: ApplyResult

status()¶

Return type:: dict[str, object]

destroy()¶

Return type:: ApplyResult

class raes_runtime.RuntimeTarget¶

Bases: object

A fully configured runtime target.

name: str¶

manifest: BackendManifest¶

provisioner: Provisioner¶

orchestrator: Orchestrator | None = None¶

evaluator: Evaluator | None = None¶

participant_runtime: ParticipantRuntime | None = None¶

time_runtime: TimeRuntime | None = None¶

observation_runtime: ObservationRuntime | None = None¶

__init__(name, manifest, provisioner, orchestrator=None, evaluator=None, participant_runtime=None, time_runtime=None, observation_runtime=None)¶

Parameters:

name (str)
manifest (BackendManifest)
provisioner (Provisioner)
orchestrator (Orchestrator | None)
evaluator (Evaluator | None)
participant_runtime (ParticipantRuntime | None)
time_runtime (TimeRuntime | None)
observation_runtime (ObservationRuntime | None)

Return type:

None

class raes_runtime.RuntimeTargetComponents¶

Bases: object

Instantiated runtime target components without a manifest.

provisioner: Provisioner¶

orchestrator: Orchestrator | None = None¶

evaluator: Evaluator | None = None¶

participant_runtime: ParticipantRuntime | None = None¶

time_runtime: TimeRuntime | None = None¶

observation_runtime: ObservationRuntime | None = None¶

__init__(provisioner, orchestrator=None, evaluator=None, participant_runtime=None, time_runtime=None, observation_runtime=None)¶

Parameters:

provisioner (Provisioner)
orchestrator (Orchestrator | None)
evaluator (Evaluator | None)
participant_runtime (ParticipantRuntime | None)
time_runtime (TimeRuntime | None)
observation_runtime (ObservationRuntime | None)

Return type:

None

class raes_runtime.RuntimeTargetDescriptor¶

Bases: object

Factories for manifest introspection and target creation.

name: str¶

manifest_factory: Callable[[...], BackendManifest]¶

components_factory: Callable[[...], RuntimeTargetComponents]¶

__init__(name, manifest_factory, components_factory)¶

Parameters:

name (str)
manifest_factory (Callable[[...], BackendManifest])
components_factory (Callable[[...], RuntimeTargetComponents])

Return type:

None

Runtime Manager¶

Runtime manager for compiled SDL runtime plans.

class raes_runtime.manager.RuntimeManager¶

Bases: _DestroyPhaseMixin, RuntimeParticipantExecutionMixin, RuntimeTimeControlMixin

Plans and executes SDL runtime work against a target.

__init__(target, *, initial_snapshot=None, stochastic_controls=(), information_state_context_resolver=None)¶

Parameters:

target (_RuntimeTarget)
initial_snapshot (RuntimeSnapshot | None)
stochastic_controls (Iterable[ExperimentStochasticControlModel])
information_state_context_resolver (ParticipantInformationStateContextResolver | None)

Return type:

None

property snapshot: RuntimeSnapshot¶

plan(scenario, snapshot=None, *, parameters=None, profile=None, artifact_availability=None, profile_authority=None, run_scope=None)¶

Parameters:

scenario (object)
snapshot (RuntimeSnapshot | None)
parameters (dict[str, object] | None)
profile (str | None)
artifact_availability (ArtifactAvailabilityContext | None)
profile_authority (PlanProfileAuthority | None)
run_scope (PlanScope | None)

Return type:

ExecutionPlan

apply(execution_plan)¶

Parameters:: execution_plan (ExecutionPlan)
Return type:: ApplyResult

status()¶

Return type:: dict[str, object]

destroy()¶

Return type:: ApplyResult

Backend Registry¶

Registry for runtime targets.

raes_runtime.registry.backend_selection_observation_runtime(manifest)¶

Parameters:: manifest (BackendManifest)
Return type:: ObservationRuntime

class raes_runtime.registry.RuntimeTarget¶

Bases: object

A fully configured runtime target.

name: str¶

manifest: BackendManifest¶

provisioner: Provisioner¶

orchestrator: Orchestrator | None = None¶

evaluator: Evaluator | None = None¶

participant_runtime: ParticipantRuntime | None = None¶

time_runtime: TimeRuntime | None = None¶

observation_runtime: ObservationRuntime | None = None¶

__init__(name, manifest, provisioner, orchestrator=None, evaluator=None, participant_runtime=None, time_runtime=None, observation_runtime=None)¶

Parameters:

name (str)
manifest (BackendManifest)
provisioner (Provisioner)
orchestrator (Orchestrator | None)
evaluator (Evaluator | None)
participant_runtime (ParticipantRuntime | None)
time_runtime (TimeRuntime | None)
observation_runtime (ObservationRuntime | None)

Return type:

None

class raes_runtime.registry.RuntimeTargetComponents¶

Bases: object

Instantiated runtime target components without a manifest.

provisioner: Provisioner¶

orchestrator: Orchestrator | None = None¶

evaluator: Evaluator | None = None¶

participant_runtime: ParticipantRuntime | None = None¶

time_runtime: TimeRuntime | None = None¶

observation_runtime: ObservationRuntime | None = None¶

__init__(provisioner, orchestrator=None, evaluator=None, participant_runtime=None, time_runtime=None, observation_runtime=None)¶

Parameters:

provisioner (Provisioner)
orchestrator (Orchestrator | None)
evaluator (Evaluator | None)
participant_runtime (ParticipantRuntime | None)
time_runtime (TimeRuntime | None)
observation_runtime (ObservationRuntime | None)

Return type:

None

class raes_runtime.registry.RuntimeTargetDescriptor¶

Bases: object

Factories for manifest introspection and target creation.

name: str¶

manifest_factory: Callable[[...], BackendManifest]¶

components_factory: Callable[[...], RuntimeTargetComponents]¶

__init__(name, manifest_factory, components_factory)¶

Parameters:

name (str)
manifest_factory (Callable[[...], BackendManifest])
components_factory (Callable[[...], RuntimeTargetComponents])

Return type:

None

class raes_runtime.registry.BackendRegistry¶

Bases: object

Registry of runtime target descriptors.

__init__()¶

Return type:: None

register(name, manifest_factory, components_factory)¶

Parameters:

name (str)
manifest_factory (Callable[[...], BackendManifest])
components_factory (Callable[[...], RuntimeTargetComponents])

Return type:

None

describe(name)¶

Parameters:: name (str)
Return type:: RuntimeTargetDescriptor

manifest(name, **config)¶

Parameters:

name (str)
config (Any)

Return type:

BackendManifest

create(name, **config)¶

Parameters:

name (str)
config (Any)

Return type:

RuntimeTarget

list_backends()¶

Return type:: list[str]

is_registered(name)¶

Parameters:: name (str)
Return type:: bool

Control Plane¶

Reference async-style control plane over runtime targets. Expose schema-oriented runtime execution as eagerly completed operations over an async-compatible API.

class raes_runtime.control_plane.RuntimeControlPlane¶

Bases: RuntimeLifecycleMixin, RuntimePlanAuthorizationMixin, RuntimeDurabilityMixin, RuntimeAdmissionMixin, WorkflowControlMixin, ParticipantControlMixin, ParticipantRetrievalMixin

Reference control plane for async runtime submission and observation.

Parameters:

target (_RuntimeTarget)
initial_snapshot (RuntimeSnapshot | None)
store (ControlPlaneStore | None)
behavior_specifications (Mapping[str, ParticipantBehaviorSpecificationRuntime] | None)
crossing_policy_resolver (ParticipantCrossingPolicyResolver | None)
information_state_context_resolver (ParticipantInformationStateContextResolver | None)
enforce_final_sink_flow_control (bool)

Return type:

None

property snapshot: RuntimeSnapshot¶

property target_name: str¶

audit_log()¶

Return type:: list[AuditEvent]

operational_apparatus_summary()¶

Return a compact operational view over existing control-plane carriers.

Return type:: dict[str, object]

submit_provisioning(plan, *, base_snapshot=None, idempotency_key='', request_fingerprint='', identity=None)¶

Parameters:

plan (ProvisioningPlan)
base_snapshot (RuntimeSnapshot | None)
idempotency_key (str)
request_fingerprint (str)
identity (object | None)

Return type:

OperationReceipt

submit_orchestration(plan, *, base_snapshot=None, idempotency_key='', request_fingerprint='', identity=None)¶

Parameters:

plan (OrchestrationPlan)
base_snapshot (RuntimeSnapshot | None)
idempotency_key (str)
request_fingerprint (str)
identity (object | None)

Return type:

OperationReceipt

submit_evaluation(plan, *, base_snapshot=None, idempotency_key='', request_fingerprint='', identity=None)¶

Parameters:

plan (EvaluationPlan)
base_snapshot (RuntimeSnapshot | None)
idempotency_key (str)
request_fingerprint (str)
identity (object | None)

Return type:

OperationReceipt

get_operation(operation_id)¶

Parameters:: operation_id (str)
Return type:: OperationStatus | None

observation_execution(operation_id)¶

Return committed metadata and explicitly retained descriptions.

Parameters:: operation_id (str)
Return type:: ObservationExecution | None

get_snapshot()¶

Return type:: RuntimeSnapshotEnvelope

Control Plane API¶

Reference HTTP/JSON adapter for the runtime control plane.

This package is a thin facade over cohesive route families:

_responses - shared response-code declarations and the receipt builder.
_auth - authentication, authorization, and identity dependencies.
_operation_routes - request guards and operation submission/read routes.
_workflow_routes - workflow cancellation and timeout reconciliation.
_participant_routes - participant execution, control, and episode routes.

create_control_plane_app (the application composition boundary) and _control_plane_api_version are defined here on purpose: test_version_classification.py patches distribution_version on this package object before calling _control_plane_api_version(), so the version lookup must resolve the package-level global rather than a submodule global. _receipt_response is re-exported for test_reference_processor.py. F401 is ignored for this facade in pyproject.toml - the “unused import” claim is false for a re-export.

raes_runtime.control_plane_api.create_control_plane_app(control_plane, *, security=None)¶

Create a reference HTTP/JSON control-plane app.

Parameters:

control_plane (RuntimeControlPlane)
security (ControlPlaneSecurityConfig | None)

Return type:

FastAPI

Control Plane Store¶

Durable storage for the per-target runtime control plane.

class raes_runtime.control_plane_store.AtomicControlPlaneStore¶

Bases: ControlPlaneStore, Protocol

Crash-atomic claim and terminal commit capabilities.

claim_record(record)¶

Parameters:: record (ControlPlaneOperationRecord)
Return type:: ControlPlaneOperationRecord

commit_terminal_operation(snapshot, record, *, audit_event=None, mode=TerminalCommitMode.SNAPSHOT_BEARING, expected_revision)¶

Parameters:

snapshot (RuntimeSnapshot)
record (ControlPlaneOperationRecord)
audit_event (AuditEvent | None)
mode (TerminalCommitMode)
expected_revision (int)

Return type:

SnapshotState

class raes_runtime.control_plane_store.AuditEvent¶

Bases: object

Append-only security and control-plane audit event.

timestamp: str¶

action: str¶

identity: str¶

allowed: bool¶

target: str¶

operation_id: str = ''¶

reason: str = ''¶

details: dict[str, Any]¶

__init__(timestamp, action, identity, allowed, target, operation_id='', reason='', details=<factory>)¶

Parameters:

timestamp (str)
action (str)
identity (str)
allowed (bool)
target (str)
operation_id (str)
reason (str)
details (dict[str, Any])

Return type:

None

class raes_runtime.control_plane_store.ControlPlaneOperationRecord¶

Bases: object

Persisted receipt/status pair for one operation.

receipt: OperationReceipt¶

status: OperationStatus¶

request_fingerprint: str = ''¶

idempotency_key: str = ''¶

result_payload: dict[str, Any] | None = None¶

decision_history_heads: dict[str, str | None]¶

result_history_heads: dict[str, str | None]¶

__init__(receipt, status, request_fingerprint='', idempotency_key='', result_payload=None, decision_history_heads=<factory>, result_history_heads=<factory>)¶

Parameters:

receipt (OperationReceipt)
status (OperationStatus)
request_fingerprint (str)
idempotency_key (str)
result_payload (dict[str, Any] | None)
decision_history_heads (dict[str, str | None])
result_history_heads (dict[str, str | None])

Return type:

None

class raes_runtime.control_plane_store.ControlPlaneStore¶

Bases: Protocol

Durable persistence capabilities for control-plane state.

load_snapshot()¶

Return type:: RuntimeSnapshot

load_snapshot_state()¶

Return type:: SnapshotState

save_snapshot(snapshot, *, expected_revision)¶

Parameters:

snapshot (RuntimeSnapshot)
expected_revision (int)

Return type:

SnapshotState

load_records()¶

Return type:: dict[str, ControlPlaneOperationRecord]

save_record(record)¶

Parameters:: record (ControlPlaneOperationRecord)
Return type:: None

find_by_idempotency(key)¶

Parameters:: key (str)
Return type:: ControlPlaneOperationRecord | None

append_audit(event)¶

Parameters:: event (AuditEvent)
Return type:: None

read_audit()¶

Return type:: list[AuditEvent]

commit_control_transition(*, participant_address, expected_head, expected_revision, snapshot, record, audit_event)¶

Parameters:

participant_address (str)
expected_head (str | None)
expected_revision (int)
snapshot (RuntimeSnapshot)
record (ControlPlaneOperationRecord)
audit_event (AuditEvent)

Return type:

SnapshotState

commit_participant_transition(*, expected_history_heads, expected_revision, snapshot, record, audit_event)¶

Parameters:

expected_history_heads (dict[str, str | None])
expected_revision (int)
snapshot (RuntimeSnapshot)
record (ControlPlaneOperationRecord)
audit_event (AuditEvent)

Return type:

SnapshotState

__init__(*args, **kwargs)¶

class raes_runtime.control_plane_store.InMemoryControlPlaneStore¶

Bases: object

Simple in-memory store.

__init__(snapshot=None)¶

Parameters:: snapshot (RuntimeSnapshot | None)
Return type:: None

load_snapshot()¶

Return type:: RuntimeSnapshot

load_snapshot_state()¶

Return type:: SnapshotState

save_snapshot(snapshot, *, expected_revision)¶

Parameters:

snapshot (RuntimeSnapshot)
expected_revision (int)

Return type:

SnapshotState

load_records()¶

Return type:: dict[str, ControlPlaneOperationRecord]

save_record(record)¶

Parameters:: record (ControlPlaneOperationRecord)
Return type:: None

claim_record(record)¶

Parameters:: record (ControlPlaneOperationRecord)
Return type:: ControlPlaneOperationRecord

commit_terminal_operation(snapshot, record, *, audit_event=None, mode=TerminalCommitMode.SNAPSHOT_BEARING, expected_revision)¶

Atomically publish a terminal record, actor audit, and revision outcome.

Parameters:

snapshot (RuntimeSnapshot)
record (ControlPlaneOperationRecord)
audit_event (AuditEvent | None)
mode (TerminalCommitMode)
expected_revision (int)

Return type:

SnapshotState

find_by_idempotency(key)¶

Parameters:: key (str)
Return type:: ControlPlaneOperationRecord | None

append_audit(event)¶

Parameters:: event (AuditEvent)
Return type:: None

read_audit()¶

Return type:: list[AuditEvent]

commit_control_transition(*, participant_address, expected_head, expected_revision, snapshot, record, audit_event)¶

Parameters:

participant_address (str)
expected_head (str | None)
expected_revision (int)
snapshot (RuntimeSnapshot)
record (ControlPlaneOperationRecord)
audit_event (AuditEvent)

Return type:

SnapshotState

commit_participant_transition(*, expected_history_heads, expected_revision, snapshot, record, audit_event, _control_head=None)¶

Parameters:

expected_history_heads (dict[str, str | None])
expected_revision (int)
snapshot (RuntimeSnapshot)
record (ControlPlaneOperationRecord)
audit_event (AuditEvent)
_control_head (tuple[str, str | None] | None)

Return type:

SnapshotState

class raes_runtime.control_plane_store.ParticipantCrossingHistoryPresence¶

Bases: str, Enum

Source-level API-423 history presence before snapshot defaults apply.

ABSENT = 'absent'¶

PRESENT_EMPTY = 'present-empty'¶

PRESENT = 'present'¶

__new__(value)¶

exception raes_runtime.control_plane_store.SnapshotRevisionConflict¶

Bases: ValueError

A snapshot-bearing commit did not consume its observed state cut.

__init__()¶

Return type:: None

class raes_runtime.control_plane_store.SnapshotState¶

Bases: object

One authoritative snapshot paired with its logical state-cut revision.

snapshot: RuntimeSnapshot¶

revision: int¶

__init__(snapshot, revision)¶

Parameters:

snapshot (RuntimeSnapshot)
revision (int)

Return type:

None

class raes_runtime.control_plane_store.TerminalCommitMode¶

Bases: str, Enum

Whether one terminal operation advances the authoritative snapshot.

SNAPSHOT_BEARING = 'snapshot-bearing'¶

OPERATION_ONLY = 'operation-only'¶

__new__(value)¶

raes_runtime.control_plane_store.participant_crossing_history_presence(payload)¶

Classify raw runtime-snapshot input without inventing historical meaning.

Parameters:: payload (dict[str, Any])
Return type:: ParticipantCrossingHistoryPresence

raes_runtime.control_plane_store.terminal_operation_audit(record)¶

Build the canonical actor-bound audit for one accepted terminal operation.

Parameters:: record (ControlPlaneOperationRecord)
Return type:: AuditEvent

Control Plane Security¶

Security policy for the per-target runtime control plane.

class raes_runtime.control_plane_security.ControlPlaneRole¶

Bases: str, Enum

Authorization roles for control-plane callers.

BACKEND = 'backend'¶

OPERATOR = 'operator'¶

AUDITOR = 'auditor'¶

__new__(value)¶

class raes_runtime.control_plane_security.ParticipantControlSubjectBinding¶

Bases: object

One authenticated principal-to-participant/controller binding.

participant_address: str¶

controller_ref: str¶

__init__(participant_address, controller_ref)¶

Parameters:

participant_address (str)
controller_ref (str)

Return type:

None

class raes_runtime.control_plane_security.ParticipantAudienceSubjectBinding¶

Bases: object

One authenticated principal-to-participant/audience binding.

participant_address: str¶

audience_scope_ref: str¶

__init__(participant_address, audience_scope_ref)¶

Parameters:

participant_address (str)
audience_scope_ref (str)

Return type:

None

class raes_runtime.control_plane_security.ControlPlaneIdentity¶

Bases: object

Authenticated control-plane principal.

identity: str¶

roles: frozenset[ControlPlaneRole]¶

target_name: str | None = None¶

participant_control_subjects: tuple[ParticipantControlSubjectBinding, ...] = ()¶

participant_audience_subjects: tuple[ParticipantAudienceSubjectBinding, ...] = ()¶

__init__(identity, roles=<factory>, target_name=None, participant_control_subjects=(), participant_audience_subjects=())¶

Parameters:

identity (str)
roles (frozenset[ControlPlaneRole])
target_name (str | None)
participant_control_subjects (tuple[ParticipantControlSubjectBinding, ...])
participant_audience_subjects (tuple[ParticipantAudienceSubjectBinding, ...])

Return type:

None

class raes_runtime.control_plane_security.ControlPlaneSecurityConfig¶

Bases: object

Reference security settings for the HTTP/JSON control-plane adapter.

Header identities are only trustworthy behind an authenticated proxy that strips caller-supplied identity headers before setting its own values.

require_verified_identity: bool = True¶

verified_header: str = 'x-raes-client-verified'¶

identity_header: str = 'x-raes-client-identity'¶

trust_proxy_identity_headers: bool = False¶

max_request_bytes: int = 1000000¶

max_pending_mutations: int = 32¶

max_pending_rejection_audits: int = 8¶

trusted_identities: Mapping[str, ControlPlaneIdentity]¶

bearer_tokens: Mapping[str, ControlPlaneIdentity]¶

classmethod strict_defaults()¶

Return fail-closed defaults with no built-in principals or tokens.

Return type:: ControlPlaneSecurityConfig

__init__(require_verified_identity=True, verified_header='x-raes-client-verified', identity_header='x-raes-client-identity', trust_proxy_identity_headers=False, max_request_bytes=1000000, max_pending_mutations=32, max_pending_rejection_audits=8, trusted_identities=<factory>, bearer_tokens=<factory>)¶

Parameters:

require_verified_identity (bool)
verified_header (str)
identity_header (str)
trust_proxy_identity_headers (bool)
max_request_bytes (int)
max_pending_mutations (int)
max_pending_rejection_audits (int)
trusted_identities (Mapping[str, ControlPlaneIdentity])
bearer_tokens (Mapping[str, ControlPlaneIdentity])

Return type:

None

Result Contracts¶

Public runtime result-contract validation helpers.

raes_runtime.result_contracts.evaluation_result_contract_diagnostics(snapshot)¶

Parameters:: snapshot (RuntimeSnapshot)
Return type:: list[Diagnostic]

raes_runtime.result_contracts.participant_episode_closure_contract_diagnostics(snapshot)¶

Validate SEM-222 episode closure records against realized episode history.

A backend RL/game termination/truncation step signal relates to an ADR-013 episode terminal reason only through an explicit, evidence-bearing closure record (EBM-10). This validates the snapshot’s participant_episode_closure_records against its append-only episode history via iter_participant_episode_closure_violations and wraps each violation in a runtime.backend-contract-invalid diagnostic. It never mutates episode history; a closure record that references a terminal fact absent from the history head is a violation, not a fact. The same check runs inside participant_runtime_state_contract_diagnostics so backend results cannot persist contradictory closure records; this helper is the focused single-concern seam over the shared iterator.

Parameters:: snapshot (RuntimeSnapshot)
Return type:: list[Diagnostic]

raes_runtime.result_contracts.participant_episode_contract_diagnostics(snapshot)¶

Validate participant-episode snapshot data against RUN-311 invariants.

Delegates to iter_participant_episode_snapshot_violations so the manager apply path and the conformance semantic-check path share one source of truth for every invariant, and wraps each violation in a runtime.backend-contract-invalid diagnostic.

Parameters:: snapshot (RuntimeSnapshot)
Return type:: list[Diagnostic]

raes_runtime.result_contracts.participant_runtime_history_transition_diagnostics(previous_snapshot, next_snapshot)¶

Validate append-only participant history preservation across an apply.

Parameters:

previous_snapshot (RuntimeSnapshot)
next_snapshot (RuntimeSnapshot)

Return type:

list[Diagnostic]

raes_runtime.result_contracts.participant_runtime_state_contract_diagnostics(snapshot, *, information_state_context_resolver=None, trusted_information_state_history=None)¶

Validate RUN-305 participant state/history snapshot data.

This combines the RUN-311 episode chain invariants with the RUN-305 behavior-history snapshot integrity checks so backend apply results cannot persist participant histories whose public map shape, identity keys, event types, episode references, or metadata boundary are invalid.

Parameters:

snapshot (RuntimeSnapshot)
information_state_context_resolver (ParticipantInformationStateContextResolver | None)
trusted_information_state_history (Mapping[str, list[dict[str, Any]]] | None)

Return type:

list[Diagnostic]

raes_runtime.result_contracts.proposition_truth_contract_diagnostics(snapshot)¶

Return fail-closed diagnostics for all truth results in a snapshot.

Parameters:: snapshot (RuntimeSnapshot)
Return type:: list[Diagnostic]

raes_runtime.result_contracts.workflow_result_contract_diagnostics(snapshot)¶

Parameters:: snapshot (RuntimeSnapshot)
Return type:: list[Diagnostic]