Runtime layer

The raes_runtime package owns live runtime control. It manages targets, backends, and their lifecycle. It also handles control-plane requests, stores operations, applies access checks, and checks backend results.

Runtime APIs use shared data types from raes_contracts for backend and control-plane calls. The control plane ignores identity headers by default. To trust them, set trust_proxy_identity_headers=True in an explicit ControlPlaneSecurityConfig.

Public API

Live runtime control surfaces for RAES SDL, loaded at their public boundary.

Lazy exports keep deterministic delivery workers from initializing backend, contract-corpus and state-owner integrations merely by importing their package.

class raes_runtime.ExperimentRunMetadata

Bases: BaseModel

Owner-supplied observations; absent facts remain absent, never inferred.

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

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

run_version: str
outcome_status: Literal['succeeded', 'failed', 'partial', 'inconclusive', 'not-evaluated']
apparatus_context: ExperimentApparatusContextModel | None
participant_implementation_provenance: ParticipantImplementationProvenanceModel | None
traceability: ExperimentRunTraceabilityModel | None
invalidation: ExperimentInvalidationModel | None
realized_bindings: tuple[RealizedBindingProvenanceModel, ...]
parameter_set: tuple[ExperimentParameterModel, ...]
evidence_artifacts: tuple[ExperimentArtifactRefModel, ...]
result_summaries: dict[str, ExperimentResultSummaryModel]
realized_form_disclosures: tuple[ExperimentRealizedFormDisclosureModel, ...]
class raes_runtime.ExperimentRecordBundle

Bases: object

ExperimentRecordBundle(runs: ‘tuple[ExperimentRunModel, …]’, sources: ‘tuple[ExperimentRecordSource, …]’, accounting: ‘ExperimentAccounting’, validation_by_run: “Mapping[str, Literal[‘passed’, ‘failed’]]”, study: ‘ExperimentStudyModel | None’ = None, study_validation: “Literal[‘passed’, ‘failed’, ‘not-performed’]” = ‘not-performed’, validation_failures: ‘Mapping[str, tuple[str, …]]’ = <factory>, retained_history: ‘tuple[ExperimentRunModel, …]’ = (), eligible_run_ids: ‘frozenset[str]’ = frozenset(), validation_records: ‘tuple[ExperimentRunModel, …]’ = ())

runs: tuple[ExperimentRunModel, ...]
sources: tuple[ExperimentRecordSource, ...]
accounting: ExperimentAccounting
validation_by_run: Mapping[str, Literal['passed', 'failed']]
study: ExperimentStudyModel | None = None
study_validation: Literal['passed', 'failed', 'not-performed'] = 'not-performed'
validation_failures: Mapping[str, tuple[str, ...]]
retained_history: tuple[ExperimentRunModel, ...] = ()
eligible_run_ids: frozenset[str] = frozenset({})
validation_records: tuple[ExperimentRunModel, ...] = ()
__init__(runs, sources, accounting, validation_by_run, study=None, study_validation='not-performed', validation_failures=<factory>, retained_history=(), eligible_run_ids=frozenset({}), validation_records=())
Parameters:
  • runs (tuple[ExperimentRunModel, ...])

  • sources (tuple[ExperimentRecordSource, ...])

  • accounting (ExperimentAccounting)

  • validation_by_run (Mapping[str, Literal['passed', 'failed']])

  • study (ExperimentStudyModel | None)

  • study_validation (Literal['passed', 'failed', 'not-performed'])

  • validation_failures (Mapping[str, tuple[str, ...]])

  • retained_history (tuple[ExperimentRunModel, ...])

  • eligible_run_ids (frozenset[str])

  • validation_records (tuple[ExperimentRunModel, ...])

Return type:

None

class raes_runtime.ExperimentRecordSource

Bases: object

Protected source artifacts retained separately from public diagnostics.

run_id: str
plan: AdmittedTrialPlanModel
realization: TrialRealization
attempts: tuple[TrialAttemptDecision, ...]
observations: tuple[TrialObservationDecision, ...]
execution_snapshots: Mapping[str, RuntimeSnapshot]
phase_states: Mapping[str, str]
operation_refs: Mapping[str, tuple[str, ...]]
operation_states: Mapping[str, str]
operation_receipts: tuple[OperationReceipt, ...]
property instantiated_scenario: BaseModel
property processor_plans: tuple[ProvisioningPlanModel, OrchestrationPlanModel, EvaluationPlanModel]
__init__(run_id, plan, realization, attempts, observations, execution_snapshots, phase_states, operation_refs, operation_states, operation_receipts)
Parameters:
  • run_id (str)

  • plan (AdmittedTrialPlanModel)

  • realization (TrialRealization)

  • attempts (tuple[TrialAttemptDecision, ...])

  • observations (tuple[TrialObservationDecision, ...])

  • execution_snapshots (Mapping[str, RuntimeSnapshot])

  • phase_states (Mapping[str, str])

  • operation_refs (Mapping[str, tuple[str, ...]])

  • operation_states (Mapping[str, str])

  • operation_receipts (tuple[OperationReceipt, ...])

Return type:

None

class raes_runtime.ExperimentAccounting

Bases: object

ExperimentAccounting(planned_runs: ‘int’, started_runs: ‘int’, unstarted_runs: ‘int’, resolved_runs: ‘int’, unresolved_runs: ‘int’, attempts: ‘int’, retry_attempts: ‘int’, replacement_runs: ‘int’, run_outcomes: ‘Mapping[str, int]’, scientific_outcomes: ‘Mapping[str, int]’, execution_outcomes: ‘Mapping[str, int]’, capture_outcomes: ‘Mapping[str, int]’, cleanup_outcomes: ‘Mapping[str, int]’, validation_outcomes: ‘Mapping[str, int]’, metric_populations: ‘Mapping[str, Mapping[str, int]]’)

planned_runs: int
started_runs: int
unstarted_runs: int
resolved_runs: int
unresolved_runs: int
attempts: int
retry_attempts: int
replacement_runs: int
run_outcomes: Mapping[str, int]
scientific_outcomes: Mapping[str, int]
execution_outcomes: Mapping[str, int]
capture_outcomes: Mapping[str, int]
cleanup_outcomes: Mapping[str, int]
validation_outcomes: Mapping[str, int]
metric_populations: Mapping[str, Mapping[str, int]]
__init__(planned_runs, started_runs, unstarted_runs, resolved_runs, unresolved_runs, attempts, retry_attempts, replacement_runs, run_outcomes, scientific_outcomes, execution_outcomes, capture_outcomes, cleanup_outcomes, validation_outcomes, metric_populations)
Parameters:
  • planned_runs (int)

  • started_runs (int)

  • unstarted_runs (int)

  • resolved_runs (int)

  • unresolved_runs (int)

  • attempts (int)

  • retry_attempts (int)

  • replacement_runs (int)

  • run_outcomes (Mapping[str, int])

  • scientific_outcomes (Mapping[str, int])

  • execution_outcomes (Mapping[str, int])

  • capture_outcomes (Mapping[str, int])

  • cleanup_outcomes (Mapping[str, int])

  • validation_outcomes (Mapping[str, int])

  • metric_populations (Mapping[str, Mapping[str, int]])

Return type:

None

class raes_runtime.ExperimentRecordArchive

Bases: Protocol

Configured immutable archive; publication never authorizes execution.

write_sources(source)
Parameters:

source (ExperimentRecordSource)

Return type:

None

write_run(run)
Parameters:

run (ExperimentRunModel)

Return type:

None

read_run(run_id, run_version)
Parameters:
  • run_id (str)

  • run_version (str)

Return type:

ExperimentRunModel

write_study(study)
Parameters:

study (ExperimentStudyModel)

Return type:

None

read_study(study_id, study_version)
Parameters:
  • study_id (str)

  • study_version (str)

Return type:

ExperimentStudyModel

__init__(*args, **kwargs)
class raes_runtime.ExperimentEvidenceReader

Bases: Protocol

__init__(*args, **kwargs)
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.ControlPlaneActorBoundary

Bases: str, Enum

EMBEDDER = 'embedder'
AUTHENTICATED_HTTP = 'authenticated-http'
UNAVAILABLE = 'unavailable'
__new__(value)
class raes_runtime.ControlPlaneCapability

Bases: str, Enum

STORE_EPHEMERAL = 'store.ephemeral'
STORE_DURABLE = 'store.durable'
STORE_ATOMIC_CLAIMS = 'store.atomic-claims'
STORE_ATOMIC_TERMINAL = 'store.atomic-terminal'
STORE_REVISION_CAS = 'store.revision-cas'
STORE_AUDIT = 'store.audit'
STORE_SCOPE_BOUND = 'store.scope-bound'
STORE_OWNER_LEASE = 'store.owner-lease'
CORE_ACTOR_CONTEXT = 'core.actor-context'
CORE_MUTATION_AUTHORITY = 'core.mutation-authority'
CORE_STARTUP_RECONCILIATION = 'core.startup-reconciliation'
HTTP_AUTHENTICATED_IDENTITY = 'http.authenticated-identity'
HTTP_SINGLE_WORKER = 'http.single-worker'
HTTP_BOUNDED_ADMISSION = 'http.bounded-admission'
HTTP_REVISION_READS = 'http.revision-reads'
__new__(value)
class raes_runtime.ControlPlaneClaim

Bases: object

ControlPlaneClaim(identifier: ‘str’, description: ‘str’)

identifier: str
description: str
__init__(identifier, description)
Parameters:
  • identifier (str)

  • description (str)

Return type:

None

class raes_runtime.ControlPlaneProfile

Bases: str, Enum

P0 = 'P0'
P1 = 'P1'
P2 = 'P2'
P3 = 'P3'
__new__(value)
class raes_runtime.ControlPlaneProfileDeclaration

Bases: object

ControlPlaneProfileDeclaration(profile: ‘ControlPlaneProfile’, label: ‘str’, guarantees: ‘tuple[ControlPlaneClaim, …]’, nonclaims: ‘tuple[ControlPlaneClaim, …]’, one_target_per_store: ‘bool’, one_run_per_store: ‘bool’, actor_boundary: ‘ControlPlaneActorBoundary’, recovery_observation: ‘RecoveryObservationRequirement’, required_capabilities: ‘frozenset[ControlPlaneCapability]’, available: ‘bool’)

profile: ControlPlaneProfile
label: str
guarantees: tuple[ControlPlaneClaim, ...]
nonclaims: tuple[ControlPlaneClaim, ...]
one_target_per_store: bool
one_run_per_store: bool
actor_boundary: ControlPlaneActorBoundary
recovery_observation: RecoveryObservationRequirement
required_capabilities: frozenset[ControlPlaneCapability]
available: bool
__init__(profile, label, guarantees, nonclaims, one_target_per_store, one_run_per_store, actor_boundary, recovery_observation, required_capabilities, available)
Parameters:
Return type:

None

class raes_runtime.ControlPlaneStoreCapabilities

Bases: object

A store’s immutable, store-owned composition facts, not a profile claim.

capabilities: frozenset[ControlPlaneCapability]
__init__(capabilities)
Parameters:

capabilities (frozenset[ControlPlaneCapability])

Return type:

None

class raes_runtime.RecoveryObservationRequirement

Bases: str, Enum

NOT_APPLICABLE = 'not-applicable'
OPTIONAL_INDETERMINATE = 'optional-indeterminate'
FUTURE_UNSPECIFIED = 'future-unspecified'
__new__(value)
class raes_runtime.RuntimeControlPlane

Bases: RuntimeRunContext

One engine for all workloads; legacy calls use its fixed default run.

__init__(target, **options)
Parameters:
Return type:

None

assign_trial(experiment_id, plan_entry_id, *, owner_id, grant=None, identity=None)

Atomically assign one original entry; identifiers grant no authority.

Parameters:
  • experiment_id (str)

  • plan_entry_id (str)

  • owner_id (str)

  • grant (AllocatorGrant | None)

  • identity (object | None)

Return type:

TrialAssignmentModel

ingest_trial_outcome(experiment_id, outcome, *, identity=None)

Verify and retain remote facts under the original admission.

Parameters:
Return type:

ExperimentProgress

verify_assigned_trial_outcome(verifier, request, outcome)

Internal bounded call to an explicitly installed original-evidence owner.

Parameters:
Return type:

None

assigned_trial_control(experiment_id, assignment_digest, *, identity=None)

Read retained coordinator intent for delivery by the downstream transport.

Parameters:
  • experiment_id (str)

  • assignment_digest (str)

  • identity (object | None)

Return type:

TrialAssignmentControlModel

advance_trial(experiment_id, plan_entry_id, *, identity=None)

Advance one assigned entry’s coordinator policy without dispatching siblings.

Parameters:
  • experiment_id (str)

  • plan_entry_id (str)

  • identity (object | None)

Return type:

ExperimentProgress

apply_assigned_trial_control(binding, control)

Internal host composition; a delivered control cannot establish cessation.

Parameters:
Return type:

tuple[bool, bool]

bind_assigned_trial(assignment, inputs, *, services, store_factory=None, identity=None)

Install an exact assigned trial, without admitting a worker experiment.

Parameters:
Return type:

AssignedTrial

require_trial_admission(attempt, services)

Internal composition check shared by local and selected trial adapters.

Parameters:
  • attempt (TrialAttemptDecision)

  • services (TrialRuntimeServices)

Return type:

None

bind_workflow(**options)

Bind exact owned artifacts before submitting reference-only delivery.

Parameters:

options (Unpack[RuntimeSequenceOptions])

Return type:

RuntimeSequenceReference

advance_workflow(reference, *, identity)
Parameters:
  • reference (RuntimeSequenceReference)

  • identity (object | None)

Return type:

str

admit_experiment(inputs, *, services, store_factory=None, identity=None, replacement=None, outcome_verifier=None)
Parameters:
  • inputs (TrialRealizationInputs)

  • services (TrialRuntimeServices)

  • store_factory (Callable[[str], ControlPlaneStore] | None)

  • identity (object | None)

  • replacement (ExperimentReplacementBinding | None)

  • outcome_verifier (TrialOutcomeVerifier | None)

Return type:

str

advance_experiment(experiment_id, *, identity=None)
Parameters:
  • experiment_id (str)

  • identity (object | None)

Return type:

ExperimentProgress

cancel_experiment(experiment_id, *, identity=None)
Parameters:
  • experiment_id (str)

  • identity (object | None)

Return type:

None

experiment_results(experiment_id, *, identity=None)
Parameters:
  • experiment_id (str)

  • identity (object | None)

Return type:

tuple[TrialUnitResult, …]

experiment_records(experiment_id, *, identity=None, metadata=None, study=None, evidence_reader=None, archive=None)

Build records for every started run, including unresolved and failed work.

Parameters:
Return type:

ExperimentRecordBundle

open_run(**options)

Open a fixed run scope without constructing another engine.

Parameters:

options (Unpack[ControlPlaneOptions])

Return type:

RuntimeRunContext

get_run(run_scope)

Select a retained context without changing the default run.

Parameters:

run_scope (str)

Return type:

RuntimeRunContext

retire_run(run_scope)

Retain completed run state and release its verified resource use.

Parameters:

run_scope (str)

Return type:

None

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:
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:
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

raes_runtime.RuntimeManager

alias of RuntimeControlPlane

class raes_runtime.MixedPhaseTransitionEvaluation

Bases: object

Bounded, value-free result from one admitted transition evaluator.

permitted: bool
attempts: int
order_ref: str
evidence_refs: tuple[str, ...]
provenance_refs: tuple[str, ...] = ()
__init__(permitted, attempts, order_ref, evidence_refs, provenance_refs=())
Parameters:
  • permitted (bool)

  • attempts (int)

  • order_ref (str)

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

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

Return type:

None

class raes_runtime.MixedRuntimeBinding

Bases: object

Trusted immutable runtime input for one sealed trial entry.

plan: AdmittedTrialPlanModel
plan_entry_id: str
profile: MixedParticipantCompositionProfileModel
context: MixedCompositionResolutionContext
components: Mapping[str, MixedRuntimeComponent]
transition_evaluators: Mapping[str, Callable[[...], MixedPhaseTransitionEvaluation]]
edge_bindings: Mapping[str, MixedEdgeExecutionBinding]
handoff_bindings: Mapping[str, MixedHandoffBinding]
backend_installations: Mapping[str, MixedBackendInstallation]
property entry: AdmittedTrialEntryModel
__init__(plan, plan_entry_id, profile, context, components, transition_evaluators=<factory>, edge_bindings=<factory>, handoff_bindings=<factory>, backend_installations=<factory>)
Parameters:
  • plan (AdmittedTrialPlanModel)

  • plan_entry_id (str)

  • profile (MixedParticipantCompositionProfileModel)

  • context (MixedCompositionResolutionContext)

  • components (Mapping[str, MixedRuntimeComponent])

  • transition_evaluators (Mapping[str, Callable[[...], MixedPhaseTransitionEvaluation]])

  • edge_bindings (Mapping[str, MixedEdgeExecutionBinding])

  • handoff_bindings (Mapping[str, MixedHandoffBinding])

  • backend_installations (Mapping[str, MixedBackendInstallation])

Return type:

None

class raes_runtime.MixedBackendInstallation

Bases: object

One obligation’s installed services and protected native artifact authority.

binding: MixedBackendExecutionBindingModel
services: Mapping[str, MixedBackendService]
time_runtime: object
evidence: OperationEvidenceResolver
property provider: object
service(pin)
Parameters:

pin (MixedBackendServiceModel)

Return type:

object

__init__(binding, services, time_runtime, evidence)
Parameters:
Return type:

None

class raes_runtime.MixedBackendService

Bases: object

An embedder-authenticated implementation pin; never resolved from backend input.

identity: MixedBackendServiceModel
implementation: object
declared_contracts: tuple[str, ...]
__init__(identity, implementation, declared_contracts)
Parameters:
Return type:

None

class raes_runtime.MixedRuntimeComponent

Bases: object

One configured effect sink joined to its exact admitted manifest.

target: RuntimeTarget
manifest: BackendManifestV2Model
envelope: BackendRealizationEnvelopeModel
__init__(target, manifest, envelope)
Parameters:
  • target (RuntimeTarget)

  • manifest (BackendManifestV2Model)

  • envelope (BackendRealizationEnvelopeModel)

Return type:

None

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
recovery_observer: RecoveryObserver | None = None
operation_provider: BackendOperationProvider | None = None
__init__(name, manifest, provisioner, orchestrator=None, evaluator=None, participant_runtime=None, time_runtime=None, observation_runtime=None, recovery_observer=None, operation_provider=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)

  • recovery_observer (RecoveryObserver | None)

  • operation_provider (BackendOperationProvider | 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
recovery_observer: RecoveryObserver | None = None
operation_provider: BackendOperationProvider | None = None
__init__(provisioner, orchestrator=None, evaluator=None, participant_runtime=None, time_runtime=None, observation_runtime=None, recovery_observer=None, operation_provider=None)
Parameters:
  • provisioner (Provisioner)

  • orchestrator (Orchestrator | None)

  • evaluator (Evaluator | None)

  • participant_runtime (ParticipantRuntime | None)

  • time_runtime (TimeRuntime | None)

  • observation_runtime (ObservationRuntime | None)

  • recovery_observer (RecoveryObserver | None)

  • operation_provider (BackendOperationProvider | 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

raes_runtime.profile_declaration(profile)

Return the canonical immutable declaration for a closed profile id.

Parameters:

profile (ControlPlaneProfile)

Return type:

ControlPlaneProfileDeclaration

Runtime manager

Compatibility entry point for the single runtime lifetime owner.

raes_runtime.manager.RuntimeManager

alias of RuntimeControlPlane

Backend registry

Registry for runtime targets.

raes_runtime.registry.backend_selection_observation_runtime(manifest)
Parameters:

manifest (BackendManifest)

Return type:

ObservationRuntime

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
recovery_observer: RecoveryObserver | None = None
operation_provider: BackendOperationProvider | None = None
__init__(provisioner, orchestrator=None, evaluator=None, participant_runtime=None, time_runtime=None, observation_runtime=None, recovery_observer=None, operation_provider=None)
Parameters:
  • provisioner (Provisioner)

  • orchestrator (Orchestrator | None)

  • evaluator (Evaluator | None)

  • participant_runtime (ParticipantRuntime | None)

  • time_runtime (TimeRuntime | None)

  • observation_runtime (ObservationRuntime | None)

  • recovery_observer (RecoveryObserver | None)

  • operation_provider (BackendOperationProvider | None)

Return type:

None

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
recovery_observer: RecoveryObserver | None = None
operation_provider: BackendOperationProvider | None = None
__init__(name, manifest, provisioner, orchestrator=None, evaluator=None, participant_runtime=None, time_runtime=None, observation_runtime=None, recovery_observer=None, operation_provider=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)

  • recovery_observer (RecoveryObserver | None)

  • operation_provider (BackendOperationProvider | 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

Shared runtime engine with a compatible fixed default run context.

class raes_runtime.control_plane.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:
Return type:

None

class raes_runtime.control_plane.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]
legacy_request_commitment: bool = False
invocation: InvocationLedger | None = None
workflow: WorkflowOperationState | None = None
reconciliation: InvocationReconciliation | None = None
inject_occurrence: InjectOccurrenceModel | None = None
inject_outcome: InjectOccurrenceOutcomeModel | None = None
inject_evidence: InjectExecutionEvidence | None = None
inject_delivery: ParticipantInjectContentModel | None = None
inject_delivery_control: ParticipantControlOccurrenceV2Model | None = None
__init__(receipt, status, request_fingerprint='', idempotency_key='', result_payload=None, decision_history_heads=<factory>, result_history_heads=<factory>, legacy_request_commitment=False, invocation=None, workflow=None, reconciliation=None, inject_occurrence=None, inject_outcome=None, inject_evidence=None, inject_delivery=None, inject_delivery_control=None)
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])

  • legacy_request_commitment (bool)

  • invocation (InvocationLedger | None)

  • workflow (WorkflowOperationState | None)

  • reconciliation (InvocationReconciliation | None)

  • inject_occurrence (InjectOccurrenceModel | None)

  • inject_outcome (InjectOccurrenceOutcomeModel | None)

  • inject_evidence (InjectExecutionEvidence | None)

  • inject_delivery (ParticipantInjectContentModel | None)

  • inject_delivery_control (ParticipantControlOccurrenceV2Model | None)

Return type:

None

class raes_runtime.control_plane.ControlPlaneOptions

Bases: TypedDict

Preserve the public constructor’s optional, keyword-only configuration.

initial_snapshot: RuntimeSnapshot | None
participant_outcome_model: RuntimeModel | None
store: ControlPlaneStore | None
behavior_specifications: Mapping[str, ParticipantBehaviorSpecificationRuntime] | None
crossing_policy_resolver: ParticipantCrossingPolicyResolver | None
information_state_context_resolver: Callable[[ParticipantInformationStateRecordModel, object | None], ParticipantInformationStateValidationContext | None] | None
participant_control: ParticipantControlRuntimeBinding | None
enforce_final_sink_flow_control: bool
materialization_archive: MaterializationArchive | None
run_scope: str
mixed_runtime: MixedRuntimeBinding | None
profile: ControlPlaneProfile | None
supervision: OperationSupervisionConfiguration
operation_evidence: OperationEvidenceResolver | None
distributed_execution: OperationDispatcher | None
inject_execution: InjectExecutionResolver | None
mixed_control: MixedControlRuntimeBinding | None
inject_delivery: ParticipantInjectRuntimeBinding | None
stochastic_controls: Iterable[ExperimentStochasticControlModel]
required_operation_guarantees: tuple[Literal['cancellation', 'effect-observation', 'cessation-evidence', 'partial-effects', 'external-fencing'], ...]
wall_clock: WallClock
class raes_runtime.control_plane.LocalControlPlaneStore

Bases: SQLRuntimeDecisionStoreMixin, LocalInvocationStoreMixin, LocalOperationRecordStoreMixin, LocalStoreScopeMigrationMixin, LocalSnapshotRevisionStoreMixin

Transactional single-host control-plane durability.

SQLite WAL transactions serialize writers across processes, keep operation and audit lookup indexed, and make participant transition commits atomic. Legacy JSON files are imported once and retained with a timestamped backup.

control_plane_capabilities = ControlPlaneStoreCapabilities(capabilities=frozenset({<ControlPlaneCapability.STORE_ATOMIC_CLAIMS: 'store.atomic-claims'>, <ControlPlaneCapability.STORE_REVISION_CAS: 'store.revision-cas'>, <ControlPlaneCapability.STORE_OWNER_LEASE: 'store.owner-lease'>, <ControlPlaneCapability.STORE_ATOMIC_TERMINAL: 'store.atomic-terminal'>, <ControlPlaneCapability.STORE_DURABLE: 'store.durable'>, <ControlPlaneCapability.STORE_AUDIT: 'store.audit'>, <ControlPlaneCapability.STORE_SCOPE_BOUND: 'store.scope-bound'>}))
__init__(base_dir, *, wall_clock=<function utc_now>)
Parameters:
  • base_dir (Path)

  • wall_clock (WallClock)

Return type:

None

admit_runtime(*, target_scope, run_scope)

Acquire sole ownership, bind scope, and only then inspect SQLite.

Parameters:
  • target_scope (str)

  • run_scope (str)

Return type:

RuntimeOwnerLease

admit_maintenance(*, target_scope, run_scope)

Acquire runtime-exclusive authority for an existing local store.

Parameters:
  • target_scope (str)

  • run_scope (str)

Return type:

RuntimeOwnerLease

acquire_runtime_lease()

Legacy entry point retained only to fail closed without scope.

Return type:

RuntimeOwnerLease

close()

Close provider resources without releasing the runtime-owner lease.

Return type:

None

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

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

Parameters:
Return type:

SnapshotState

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:
Return type:

SnapshotState

commit_participant_transition(*, expected_history_heads, expected_revision, snapshot, record, audit_event, _control_head=None)
Parameters:
Return type:

SnapshotState

class raes_runtime.control_plane.ParticipantControlEffectRealization

Bases: object

Bounded, value-independent outcome of one dispatched effect.

effect_id: str
disposition: str
receipt_ref: str
__init__(effect_id, disposition, receipt_ref)
Parameters:
  • effect_id (str)

  • disposition (str)

  • receipt_ref (str)

Return type:

None

class raes_runtime.control_plane.ParticipantControlResolution

Bases: object

Owner-resolved admitted request, support and incumbent gate for one cut.

request: ParticipantControlRequestModel | ParticipantControlRequestV2Model
support: tuple[ControlEffectiveSupportModel, ...] | tuple[ControlSupportAssessmentV2Model, ...]
incumbent_gate_disposition: str
incumbent_gate_evidence: ControlArtifactReferenceModel
__init__(request, support, incumbent_gate_disposition, incumbent_gate_evidence)
Parameters:
  • request (ParticipantControlRequestModel | ParticipantControlRequestV2Model)

  • support (tuple[ControlEffectiveSupportModel, ...] | tuple[ControlSupportAssessmentV2Model, ...])

  • incumbent_gate_disposition (str)

  • incumbent_gate_evidence (ControlArtifactReferenceModel)

Return type:

None

class raes_runtime.control_plane.ParticipantControlRuntimeBinding

Bases: object

Immutable admitted selection joined to its exact provider instances.

selection: ParticipantControlSelectionModel | ParticipantControlSelectionV2Model
providers: Mapping[str, ParticipantControlProvider | ParticipantControlProviderV2]
resolver: ParticipantControlRuntimeResolver | ParticipantControlRuntimeResolverV2
stages: Mapping[str, ParticipantControlStageBinding] | None = None
contract_digests: Mapping[str, str] | None = None
__init__(selection, providers, resolver, stages=None, contract_digests=None)
Parameters:
  • selection (ParticipantControlSelectionModel | ParticipantControlSelectionV2Model)

  • providers (Mapping[str, ParticipantControlProvider | ParticipantControlProviderV2])

  • resolver (ParticipantControlRuntimeResolver | ParticipantControlRuntimeResolverV2)

  • stages (Mapping[str, ParticipantControlStageBinding] | None)

  • contract_digests (Mapping[str, str] | None)

Return type:

None

class raes_runtime.control_plane.ParticipantControlRuntimeResolver

Bases: Protocol

Trusted owner resolution, declared like the incumbent policy resolver.

resolve returns the admitted request for the live cut, or None when modular control does not apply to it. validation_context supplies the independently resolved owner facts API-424 checks the evaluation against; neither may be satisfied from provider output. It is called for retained evaluations as well as fresh ones: resolve the original admitted inputs and current effect approval. effect_operation returns the incumbent owner input for one admitted effect, or None for an effect this apparatus has no owner for — declared here, like the rest of the protocol, rather than discovered per effect.

resolve(**coordinates)
Parameters:

coordinates (object)

Return type:

ParticipantControlResolution | None

validation_context(evaluation)
Parameters:

evaluation (object)

Return type:

ParticipantControlValidationContext | ParticipantControlValidationContextV2

effect_operation(request, context)
Parameters:
  • request (object)

  • context (object)

Return type:

object | None

__init__(*args, **kwargs)
class raes_runtime.control_plane.RuntimeControlPlane

Bases: RuntimeRunContext

One engine for all workloads; legacy calls use its fixed default run.

__init__(target, **options)
Parameters:
Return type:

None

assign_trial(experiment_id, plan_entry_id, *, owner_id, grant=None, identity=None)

Atomically assign one original entry; identifiers grant no authority.

Parameters:
  • experiment_id (str)

  • plan_entry_id (str)

  • owner_id (str)

  • grant (AllocatorGrant | None)

  • identity (object | None)

Return type:

TrialAssignmentModel

ingest_trial_outcome(experiment_id, outcome, *, identity=None)

Verify and retain remote facts under the original admission.

Parameters:
Return type:

ExperimentProgress

verify_assigned_trial_outcome(verifier, request, outcome)

Internal bounded call to an explicitly installed original-evidence owner.

Parameters:
Return type:

None

assigned_trial_control(experiment_id, assignment_digest, *, identity=None)

Read retained coordinator intent for delivery by the downstream transport.

Parameters:
  • experiment_id (str)

  • assignment_digest (str)

  • identity (object | None)

Return type:

TrialAssignmentControlModel

advance_trial(experiment_id, plan_entry_id, *, identity=None)

Advance one assigned entry’s coordinator policy without dispatching siblings.

Parameters:
  • experiment_id (str)

  • plan_entry_id (str)

  • identity (object | None)

Return type:

ExperimentProgress

apply_assigned_trial_control(binding, control)

Internal host composition; a delivered control cannot establish cessation.

Parameters:
Return type:

tuple[bool, bool]

bind_assigned_trial(assignment, inputs, *, services, store_factory=None, identity=None)

Install an exact assigned trial, without admitting a worker experiment.

Parameters:
Return type:

AssignedTrial

require_trial_admission(attempt, services)

Internal composition check shared by local and selected trial adapters.

Parameters:
  • attempt (TrialAttemptDecision)

  • services (TrialRuntimeServices)

Return type:

None

bind_workflow(**options)

Bind exact owned artifacts before submitting reference-only delivery.

Parameters:

options (Unpack[RuntimeSequenceOptions])

Return type:

RuntimeSequenceReference

advance_workflow(reference, *, identity)
Parameters:
  • reference (RuntimeSequenceReference)

  • identity (object | None)

Return type:

str

admit_experiment(inputs, *, services, store_factory=None, identity=None, replacement=None, outcome_verifier=None)
Parameters:
  • inputs (TrialRealizationInputs)

  • services (TrialRuntimeServices)

  • store_factory (Callable[[str], ControlPlaneStore] | None)

  • identity (object | None)

  • replacement (ExperimentReplacementBinding | None)

  • outcome_verifier (TrialOutcomeVerifier | None)

Return type:

str

advance_experiment(experiment_id, *, identity=None)
Parameters:
  • experiment_id (str)

  • identity (object | None)

Return type:

ExperimentProgress

cancel_experiment(experiment_id, *, identity=None)
Parameters:
  • experiment_id (str)

  • identity (object | None)

Return type:

None

experiment_results(experiment_id, *, identity=None)
Parameters:
  • experiment_id (str)

  • identity (object | None)

Return type:

tuple[TrialUnitResult, …]

experiment_records(experiment_id, *, identity=None, metadata=None, study=None, evidence_reader=None, archive=None)

Build records for every started run, including unresolved and failed work.

Parameters:
Return type:

ExperimentRecordBundle

open_run(**options)

Open a fixed run scope without constructing another engine.

Parameters:

options (Unpack[ControlPlaneOptions])

Return type:

RuntimeRunContext

get_run(run_scope)

Select a retained context without changing the default run.

Parameters:

run_scope (str)

Return type:

RuntimeRunContext

retire_run(run_scope)

Retain completed run state and release its verified resource use.

Parameters:

run_scope (str)

Return type:

None

raes_runtime.control_plane.operation_actor_scope(identity)

Return the immutable actor and authorization scope for a typed identity.

Parameters:

identity (object | None)

Return type:

tuple[str, tuple[str, …]]

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, per-route transport authority, and identity dependencies. App construction fails unless every served route declares one authority; the resulting (method, path) inventory is exposed as app.state.control_plane_route_authority.

  • _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, profile=None)

Create a reference HTTP/JSON control-plane app.

Parameters:
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, *, legacy_request_fingerprint='', new_claim_blocked=None)
Parameters:
  • record (ControlPlaneOperationRecord)

  • legacy_request_fingerprint (str)

  • new_claim_blocked (Literal['current-state', 'indeterminate', 'stale-base-snapshot'] | None)

Return type:

ControlPlaneOperationRecord

commit_terminal_operation(snapshot, record, *, audit_event=None, mode=TerminalCommitMode.SNAPSHOT_BEARING, expected_revision)
Parameters:
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]
legacy_request_commitment: bool = False
invocation: InvocationLedger | None = None
workflow: WorkflowOperationState | None = None
reconciliation: InvocationReconciliation | None = None
inject_occurrence: InjectOccurrenceModel | None = None
inject_outcome: InjectOccurrenceOutcomeModel | None = None
inject_evidence: InjectExecutionEvidence | None = None
inject_delivery: ParticipantInjectContentModel | None = None
inject_delivery_control: ParticipantControlOccurrenceV2Model | None = None
__init__(receipt, status, request_fingerprint='', idempotency_key='', result_payload=None, decision_history_heads=<factory>, result_history_heads=<factory>, legacy_request_commitment=False, invocation=None, workflow=None, reconciliation=None, inject_occurrence=None, inject_outcome=None, inject_evidence=None, inject_delivery=None, inject_delivery_control=None)
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])

  • legacy_request_commitment (bool)

  • invocation (InvocationLedger | None)

  • workflow (WorkflowOperationState | None)

  • reconciliation (InvocationReconciliation | None)

  • inject_occurrence (InjectOccurrenceModel | None)

  • inject_outcome (InjectOccurrenceOutcomeModel | None)

  • inject_evidence (InjectExecutionEvidence | None)

  • inject_delivery (ParticipantInjectContentModel | None)

  • inject_delivery_control (ParticipantControlOccurrenceV2Model | 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:
Return type:

SnapshotState

load_records()
Return type:

dict[str, ControlPlaneOperationRecord]

save_record(record)
Parameters:

record (ControlPlaneOperationRecord)

Return type:

None

find_by_idempotency(key, *, context=None)
Parameters:
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:
Return type:

SnapshotState

commit_participant_transition(*, expected_history_heads, expected_revision, snapshot, record, audit_event)
Parameters:
Return type:

SnapshotState

__init__(*args, **kwargs)
class raes_runtime.control_plane_store.InMemoryControlPlaneStore

Bases: MemoryRuntimeDecisionStoreMixin

Simple in-memory store.

control_plane_capabilities = ControlPlaneStoreCapabilities(capabilities=frozenset({<ControlPlaneCapability.STORE_ATOMIC_CLAIMS: 'store.atomic-claims'>, <ControlPlaneCapability.STORE_REVISION_CAS: 'store.revision-cas'>, <ControlPlaneCapability.STORE_EPHEMERAL: 'store.ephemeral'>, <ControlPlaneCapability.STORE_SCOPE_BOUND: 'store.scope-bound'>, <ControlPlaneCapability.STORE_AUDIT: 'store.audit'>, <ControlPlaneCapability.STORE_ATOMIC_TERMINAL: 'store.atomic-terminal'>}))
__init__(snapshot=None)
Parameters:

snapshot (RuntimeSnapshot | None)

Return type:

None

bind_scope(*, target_scope, run_scope)

Admit one active owner and pin the store’s target/run scope.

Parameters:
  • target_scope (str)

  • run_scope (str)

Return type:

_InMemoryRuntimeOwner

load_snapshot()
Return type:

RuntimeSnapshot

load_snapshot_state()
Return type:

SnapshotState

save_snapshot(snapshot, *, expected_revision)
Parameters:
Return type:

SnapshotState

load_records()
Return type:

dict[str, ControlPlaneOperationRecord]

load_operation_changes(cursor=None)
Parameters:

cursor (int | None)

Return type:

OperationChanges

save_record(record)
Parameters:

record (ControlPlaneOperationRecord)

Return type:

None

claim_record(record, *, legacy_request_fingerprint='', new_claim_blocked=None)
Parameters:
  • record (ControlPlaneOperationRecord)

  • legacy_request_fingerprint (str)

  • new_claim_blocked (Literal['current-state', 'indeterminate', 'stale-base-snapshot'] | None)

Return type:

ControlPlaneOperationRecord

admit_execution_generation()
Return type:

int

effect_admission_stopped()
Return type:

bool

stop_effect_admission(event)
Parameters:

event (AuditEvent)

Return type:

None

commit_invocation_transition(expected, record, *, audit_event)
Parameters:
Return type:

SnapshotState

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:
Return type:

SnapshotState

find_by_idempotency(key, *, context=None)
Parameters:
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:
Return type:

SnapshotState

commit_participant_transition(*, expected_history_heads, expected_revision, snapshot, record, audit_event, _control_head=None)
Parameters:
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: ConflictError

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:
Return type:

None

class raes_runtime.control_plane_store.RuntimeAdmittedControlPlaneStore

Bases: Protocol

Durable provider that must be admitted before any store access.

admit_runtime(*, target_scope, run_scope)
Parameters:
  • target_scope (str)

  • run_scope (str)

Return type:

object

close()
Return type:

None

__init__(*args, **kwargs)
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.idempotency_claim_identity(context, key)

Return the provider-private claim identity inside one target/run store.

Parameters:
Return type:

tuple[str, OperationKind, str]

raes_runtime.control_plane_store.require_operation_record_scopes(records, *, target_scope, run_scope)

Reject persisted operations outside the runtime-admitted store scope.

Parameters:
Return type:

None

raes_runtime.control_plane_store.require_idempotency_key(key)

Validate the one client-key shape used by every operation family.

Parameters:

key (str)

Return type:

str

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

Assigned trials

The Execute assigned trials guide describes coordinator admission, selected host execution, cancellation, and checked outcome ingestion.

One selected execution binding inside the shared runtime engine.

raes_runtime.runtime_assigned_trial.assigned_attempt(assignment)

Build the local ledger decision from the exact portable authorization.

Parameters:

assignment (TrialAssignmentModel)

Return type:

TrialAttemptDecision

class raes_runtime.runtime_assigned_trial.AssignedTrial

Bases: object

Public bound BackendTrialUnit; transport and host placement are downstream.

__init__(engine, assignment, inputs, *, store, services, identity)
Parameters:
Return type:

None

property realization: TrialRealization

Detached in-process processor output for installed composition.

owns_attempt(attempt, services)
Parameters:
  • attempt (TrialAttemptDecision)

  • services (TrialRuntimeServices)

Return type:

bool

require_services(services)
Parameters:

services (TrialRuntimeServices)

Return type:

None

property assignment: TrialAssignmentModel
property assignment_digest: str
property experiment_id: str
property owner_id: str
property request: TrialUnitRequest
require_owner(identity)
Parameters:

identity (object | None)

Return type:

None

attach(unit)
Parameters:

unit (RuntimeTrialUnit)

Return type:

None

outcome(*, identity=None)
Parameters:

identity (object | None)

Return type:

TrialOutcomeModel

advance(*, identity=None, control=None)
Parameters:
Return type:

ExperimentProgress

execute_trial(request, *, identity=<object object>)
Parameters:
  • request (TrialUnitRequest)

  • identity (object | None)

Return type:

TrialUnitResult

Closed process-boundary composition of existing trial contracts.

class raes_contracts.assigned_trial.TrialAssignmentModel

Bases: TrialHandoffModel

Data binding only; trusted composition supplies authentication.

schema_version: Literal['assigned-trial/v1']
plan: AdmittedTrialPlanModel
plan_entry_id: Identity
execution_attempt_id: Identity
attempt: Annotated[int, Field(strict=True, ge=1, le=1000)]
started_at: Rfc3339DateTimeString
deadline: Rfc3339DateTimeString
target_scope: Identity
owner_id: Identity
owner_generation: Annotated[int, Field(strict=True, ge=1, le=1)]
instantiated_sdl_digest: Digest
processor_plan_refs: tuple[TrialProcessorPlanReferenceModel, ...]
effective_parallelism: Annotated[int, Field(strict=True, ge=1, le=MAX_TRIAL_PARALLELISM)]
binding()
Return type:

TrialAssignmentModel

property experiment_id: str
property root_plan_digest: str
model_config = {'extra': 'forbid', 'frozen': True, 'hide_input_in_errors': True, 'revalidate_instances': 'always'}

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

class raes_contracts.assigned_trial.TrialAssignmentControlModel

Bases: TrialHandoffModel

schema_version: Literal['assigned-trial-control/v1']
assignment_digest: Digest
cancelled: StrictBool
prepare_retry: StrictBool
model_config = {'extra': 'forbid', 'frozen': True, 'hide_input_in_errors': True, 'revalidate_instances': 'always'}

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

class raes_contracts.assigned_trial.TrialOutcomeModel

Bases: TrialHandoffModel

Original observations, without fabricated terminal facts for lost work.

model_config = {'extra': 'forbid', 'frozen': True, 'hide_input_in_errors': True, 'json_schema_extra': {'allOf': [{'if': {'properties': {'progress': {'const': 'completed'}}, 'required': ['progress']}, 'then': {'properties': {'facts': {'allOf': [{'contains': {'properties': {'observation': {'properties': {'kind': {'const': 'execution'}}, 'required': ['kind']}}, 'required': ['observation']}}, {'contains': {'properties': {'observation': {'properties': {'kind': {'const': 'cleanup'}}, 'required': ['kind']}}, 'required': ['observation']}}]}}, 'required': ['facts']}}]}, 'revalidate_instances': 'always'}

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

schema_version: Literal['trial-outcome/v1']
assignment_digest: Digest
facts: tuple[TrialFactModel, ...]
operations: tuple[TrialOperationModel, ...]
configuration_state: PhaseState
capture_state: PhaseState
retry_state: PhaseState
progress: Literal['progress', 'pending', 'indeterminate', 'cleanup-failed', 'completed']
unique_facts()
Return type:

TrialOutcomeModel

raes_contracts.assigned_trial.trial_attempt_id(experiment_id, entry_id, ordinal)
Parameters:
  • experiment_id (str)

  • entry_id (str)

  • ordinal (int)

Return type:

str

class raes_runtime.runtime_trial_services.TrialOutcomeVerifier

Bases: Protocol

Installed authorized reader, never a worker-supplied assertion.

Verify original native execution records and their request/predecessor/result commitments against the request. Resolve original evidence through its owners. Establish configuration, cessation, capture and cleanup facts, including their native validation provenance. Reuse OperationEvidenceResolver and the original runtime’s checked records. Mere carrier equality or a claimed digest cannot establish physical truth. Raise on missing, changed or unverified evidence.

verify_outcome(request, outcome)
Parameters:
Return type:

None

__init__(*args, **kwargs)

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.ControlPlaneRouteAuthority

Bases: str, Enum

Transport authority that one served P2 route declares.

P2 is a host-mediated, administrative-only surface (issue #1356). Every authority except the value-free public probe admits a privileged, target-bound service identity; none is participant, controller or disclosure authority. Participant/audience and participant/controller bindings are applied by the core operation after this admission.

PUBLIC_PROBE = 'public-probe'
ADMINISTRATIVE_READ = 'administrative-read'
ADMINISTRATIVE_MUTATION = 'administrative-mutation'
OPERATOR_RESOLUTION = 'operator-resolution'
__new__(value)
raes_runtime.control_plane_security.ROUTE_AUTHORITY_ROLES: Mapping[ControlPlaneRouteAuthority, frozenset[ControlPlaneRole]] = mappingproxy({<ControlPlaneRouteAuthority.ADMINISTRATIVE_READ: 'administrative-read'>: frozenset({<ControlPlaneRole.AUDITOR: 'auditor'>, <ControlPlaneRole.OPERATOR: 'operator'>, <ControlPlaneRole.BACKEND: 'backend'>}), <ControlPlaneRouteAuthority.ADMINISTRATIVE_MUTATION: 'administrative-mutation'>: frozenset({<ControlPlaneRole.OPERATOR: 'operator'>, <ControlPlaneRole.BACKEND: 'backend'>}), <ControlPlaneRouteAuthority.OPERATOR_RESOLUTION: 'operator-resolution'>: frozenset({<ControlPlaneRole.OPERATOR: 'operator'>})})

Roles admitted by each authenticated route authority.

A read role admits full snapshots and operational reads as well as participant views (API-404-C3); an audience binding does not narrow it.

raes_runtime.control_plane_security.ROUTE_AUTHORITY_METHODS: Mapping[ControlPlaneRouteAuthority, frozenset[str]] = mappingproxy({<ControlPlaneRouteAuthority.PUBLIC_PROBE: 'public-probe'>: frozenset({'GET'}), <ControlPlaneRouteAuthority.ADMINISTRATIVE_READ: 'administrative-read'>: frozenset({'GET'}), <ControlPlaneRouteAuthority.ADMINISTRATIVE_MUTATION: 'administrative-mutation'>: frozenset({'POST', 'PUT', 'DELETE', 'PATCH'}), <ControlPlaneRouteAuthority.OPERATOR_RESOLUTION: 'operator-resolution'>: frozenset({'POST', 'PUT', 'DELETE', 'PATCH'})})

HTTP methods each route authority may serve.

Read authorities admit the auditor role, so they must never front a state change; mutating authorities must never be reachable by a safe method.

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:
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]
__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

classmethod strict_defaults()

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

Return type:

ControlPlaneSecurityConfig

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:
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]