Runtime

ActionRuntime coordinates the lifecycle. Its public methods are async and always require an explicit typed action definition.

runtime

Framework-neutral confirm-first action orchestration.

ActionRuntime

ActionRuntime(*, store: ActionStore, retention_store: RetentionStore | None = None, clock: Clock | None = None, identifiers: IdentifierProvider | None = None, event_sink: EventSink | None = None, runtime_revision: str | None = None)

Coordinates host-owned controls without owning host business truth.

prepare async

prepare(definition: ActionDefinition[CommandT, PrivateSnapshotT, PreviewT, ResultT], *, tenant_reference: str, command: CommandT, requesting_principal: RequestingPrincipal, proposing_agent: ProposingAgent | None = None) -> ActionOperationResult

record_authority async

record_authority(definition: ActionDefinition[CommandT, PrivateSnapshotT, PreviewT, ResultT], *, evidence: AuthorityEvidence, authenticated_authority: ConfirmingAuthority, proposal_reference: str | None = None) -> ActionOperationResult

expire_due async

expire_due(definition: ActionDefinition[CommandT, PrivateSnapshotT, PreviewT, ResultT], *, tenant_reference: str, proposal_reference: str) -> ActionOperationResult

Expire an unexecuted proposal once its prepared lifetime has elapsed.

execute async

execute(definition: ActionDefinition[CommandT, PrivateSnapshotT, PreviewT, ResultT], *, tenant_reference: str, proposal_reference: str) -> ActionOperationResult

reconcile async

reconcile(definition: ActionDefinition[CommandT, PrivateSnapshotT, PreviewT, ResultT], *, tenant_reference: str, proposal_reference: str) -> ActionOperationResult

read async

read(definition: ActionDefinition[CommandT, PrivateSnapshotT, PreviewT, ResultT], *, proposal_reference: str, context: ReadContext) -> ProposalView

erase async

erase(definition: ActionDefinition[CommandT, PrivateSnapshotT, PreviewT, ResultT], *, proposal_reference: str, context: ReadContext) -> ActionOperationResult

ActionOperationResult

Bases: ExperimentalModel

proposal_reference instance-attribute

proposal_reference: SafeReference

lifecycle_status instance-attribute

lifecycle_status: LifecycleStatus

outcome instance-attribute

outcome: OperationOutcome

revision instance-attribute

revision: int

display_preview class-attribute instance-attribute

display_preview: JsonObject = Field(default_factory=dict)

safe_result class-attribute instance-attribute

safe_result: JsonObject | None = None

fresh_proposal_reference class-attribute instance-attribute

fresh_proposal_reference: SafeReference | None = None

reason_code class-attribute instance-attribute

reason_code: SafeReference | None = None

is_terminal property

is_terminal: bool

Whether the proposal lifecycle has no valid transition left.

needs_reconciliation property

needs_reconciliation: bool

Whether authoritative reconciliation may advance this proposal.

ProposalView

Bases: ExperimentalModel

proposal_reference instance-attribute

proposal_reference: SafeReference

lifecycle_status instance-attribute

lifecycle_status: LifecycleStatus

revision instance-attribute

revision: int

display_preview instance-attribute

display_preview: JsonObject

receipts instance-attribute

receipts: tuple[Receipt, ...]

safe_result class-attribute instance-attribute

safe_result: JsonObject | None = None

erased instance-attribute

erased: bool

OperationOutcome

Bases: StrEnum

PREPARED class-attribute instance-attribute

PREPARED = 'prepared'

AUTHORITY_PENDING class-attribute instance-attribute

AUTHORITY_PENDING = 'authority_pending'

AUTHORIZED class-attribute instance-attribute

AUTHORIZED = 'authorized'

DENIED class-attribute instance-attribute

DENIED = 'denied'

BLOCKED class-attribute instance-attribute

BLOCKED = 'blocked'

STALE class-attribute instance-attribute

STALE = 'stale'

IN_PROGRESS class-attribute instance-attribute

IN_PROGRESS = 'in_progress'

EXPIRED class-attribute instance-attribute

EXPIRED = 'expired'

REPLAYED class-attribute instance-attribute

REPLAYED = 'replayed'

CONFLICT class-attribute instance-attribute

CONFLICT = 'conflict'

VERIFICATION_PENDING class-attribute instance-attribute

VERIFICATION_PENDING = 'verification_pending'

VERIFIED class-attribute instance-attribute

VERIFIED = 'verified'

PARTIALLY_SUCCEEDED class-attribute instance-attribute

PARTIALLY_SUCCEEDED = 'partially_succeeded'

FAILED_KNOWN class-attribute instance-attribute

FAILED_KNOWN = 'failed_known'

FAILED_UNKNOWN class-attribute instance-attribute

FAILED_UNKNOWN = 'failed_unknown'

VERIFICATION_UNRESOLVED class-attribute instance-attribute

VERIFICATION_UNRESOLVED = 'verification_unresolved'

RESEND_ALLOWED class-attribute instance-attribute

RESEND_ALLOWED = 'resend_allowed'

ERASED class-attribute instance-attribute

ERASED = 'erased'

RuntimeReasonCode

Bases: StrEnum

Reason codes generated by the runtime; hosts may still return their own.

PREPARE_DENIED class-attribute instance-attribute

PREPARE_DENIED = 'prepare_denied'

AUTHORITY_REJECTED class-attribute instance-attribute

AUTHORITY_REJECTED = 'authority_rejected'

PROPOSAL_EXPIRED class-attribute instance-attribute

PROPOSAL_EXPIRED = 'proposal_expired'

PRIVATE_SNAPSHOT_UNAVAILABLE class-attribute instance-attribute

PRIVATE_SNAPSHOT_UNAVAILABLE = 'private_snapshot_unavailable'

PROPOSAL_COMMITMENT_UNAVAILABLE class-attribute instance-attribute

PROPOSAL_COMMITMENT_UNAVAILABLE = 'proposal_commitment_unavailable'

AUTHORITY_EXPIRED class-attribute instance-attribute

AUTHORITY_EXPIRED = 'authority_expired'

AUTHORITY_NO_LONGER_SATISFIED class-attribute instance-attribute

AUTHORITY_NO_LONGER_SATISFIED = 'authority_no_longer_satisfied'

REAUTHORIZATION_FAILED class-attribute instance-attribute

REAUTHORIZATION_FAILED = 'reauthorization_failed'

VERIFICATION_RETRIES_EXHAUSTED class-attribute instance-attribute

VERIFICATION_RETRIES_EXHAUSTED = 'verification_retries_exhausted'

MATERIAL_DRIFT class-attribute instance-attribute

MATERIAL_DRIFT = 'material_drift'

PARTIAL_NOT_DECLARED class-attribute instance-attribute

PARTIAL_NOT_DECLARED = 'partial_not_declared'

VERIFIED_TERMINAL_FAILURE class-attribute instance-attribute

VERIFIED_TERMINAL_FAILURE = 'verified_terminal_failure'

AUTHORITATIVE_FINAL_ABSENCE class-attribute instance-attribute

AUTHORITATIVE_FINAL_ABSENCE = 'authoritative_final_absence'

Clock

Bases: Protocol

now

now() -> datetime

IdentifierProvider

Bases: Protocol

new

new(prefix: str) -> str

SystemClock

Production default that returns the current timezone-aware UTC time.

now

now() -> datetime

UuidIdentifiers

Production default that creates opaque, cryptographically random references.

new

new(prefix: str) -> str

ProposalNotFoundError

ProposalNotFoundError()

Bases: LookupError

AuthorizationDeniedError

Bases: PermissionError

InvalidAuthorityEvidenceError

Bases: ValueError

InvalidActionResultError

Bases: RuntimeError

RetentionStoreUnavailableError

Bases: RuntimeError