Public API

The supported import surface is re-exported from threvo_actions. Optional adapter types live in their own modules so importing the core never imports a database or agent framework.

Versioned support

Version 0.1.3 freezes the documented Python imports and CLI for the 0.1.x line. Serialized interoperability forms remain experimental. See Versioning.

threvo_actions

Experimental confirm-first financial action contracts.

EffectKind module-attribute

EffectKind = Literal['single', 'itemized']

Participant module-attribute

Participant = Annotated[RequestingPrincipal | ProposingAgent | ConfirmingAuthority | GovernedExecutor | AuthoritativeTarget | EvidenceConsumer, Field(discriminator='kind')]

Receipt module-attribute

Receipt = Annotated[ProposalReceipt | AuthorityReceipt | ExecutionReceipt | VerificationReceipt, Field(discriminator='receipt_type')]

__all__ module-attribute

__all__ = ['Action', 'ActionConfigurationError', 'ActionDefinition', 'ActionNotRegisteredError', 'ActionOperationResult', 'ActionRegistry', 'ActionRuntime', 'ActionStore', 'ActionType', 'AnyApproval', 'ApprovalReasonCode', 'AuthoritativeTarget', 'AuthorityBinding', 'AuthorityDecision', 'AuthorityEvaluation', 'AuthorityEvaluatorPort', 'AuthorityEvidence', 'AuthorityReceipt', 'AuthorityReceiptStatus', 'AuthorityValidationFailure', 'AuthorityValidationResult', 'AuthorizationDeniedError', 'AuthorizationPort', 'AuthorizationResult', 'CanonicalizationError', 'Clock', 'CommitmentProvider', 'ConfirmingAuthority', 'DecisionContext', 'DefinitionConformanceError', 'DefinitionTypeMismatchError', 'DuplicateActionError', 'EffectClaimResult', 'EffectKind', 'EventSink', 'EvidenceConsumer', 'ExecutionContext', 'ExecutionReceipt', 'ExecutionReceiptStatus', 'ExecutionResult', 'ExecutionStatus', 'ExternalReference', 'GovernedExecutor', 'GovernedExecutorPort', 'IdentifierProvider', 'InvalidActionResultError', 'InvalidAuthorityEvidenceError', 'ItemOutcome', 'ItemOutcomeStatus', 'KeyedCommitment', 'LifecycleStatus', 'MOfNApprovals', 'MemoryActionStore', 'Money', 'NoopEventSink', 'OperationOutcome', 'Participant', 'PreparationContext', 'PreparationPort', 'PreparedAction', 'ProposalAlreadyExistsError', 'ProposalNotFoundError', 'ProposalReceipt', 'ProposalReceiptStatus', 'ProposalView', 'ProposingAgent', 'ProtectedPayload', 'ProtectionCodec', 'ReadContext', 'Receipt', 'RequestingPrincipal', 'ResolvedState', 'RetentionPort', 'RetentionStore', 'RetentionStoreUnavailableError', 'RuntimeAttributionError', 'RuntimeEvent', 'RuntimeEventType', 'RuntimeReasonCode', 'SingleApproval', 'StateResolverPort', 'StoreInvariantError', 'StoredProposal', 'SystemClock', 'UuidIdentifiers', 'VerificationReceipt', 'VerificationReceiptStatus', 'VerificationResult', 'VerificationStatus', 'VerifierPort', 'assert_definition_conforms', 'authority_evidence_matches_binding', 'canonicalize_v1', 'commitment_payload_v1', 'resolve_runtime_revision', 'validate_authority_evidence', 'validate_proposal_create', 'validate_proposal_update']

__version__ module-attribute

__version__ = '0.1.3'

Action

Action(*, authority_evaluator: AuthorityEvaluatorPort, commitment_provider: CommitmentProvider, protection_codec: ProtectionCodec)

Bases: ABC, Generic[CommandT, PrivateSnapshotT, PreviewT, ResultT]

Author an action as one typed object without creating a second runtime path.

Deployment services remain constructor-injected. Immutable action metadata stays visible on the subclass. to_definition is the only bridge to the runtime.

action_type class-attribute

action_type: ActionType

proposal_ttl class-attribute

proposal_ttl: timedelta

executor_identity class-attribute

executor_identity: GovernedExecutor

target_identity class-attribute

target_identity: AuthoritativeTarget

authority_audience class-attribute

authority_audience: str

authority_channel_assurance class-attribute

authority_channel_assurance: str

verification_delay class-attribute

verification_delay: timedelta = timedelta(0)

max_verification_attempts class-attribute

max_verification_attempts: int = 3

effect_kind class-attribute

effect_kind: EffectKind = 'single'

allow_resend_after_final_absence class-attribute

allow_resend_after_final_absence: bool = False

verification_lease_duration class-attribute

verification_lease_duration: timedelta = timedelta(minutes=1)

semantic_idempotency_strategy class-attribute

semantic_idempotency_strategy: Literal['host_defined'] = 'host_defined'

__init_subclass__

__init_subclass__(**kwargs: object) -> None

to_definition

to_definition() -> ActionDefinition[CommandT, PrivateSnapshotT, PreviewT, ResultT]

Compile this authoring facade to the runtime's public plumbing.

prepare abstractmethod async

prepare(command: CommandT, *, context: PreparationContext) -> PreparedAction[PrivateSnapshotT, PreviewT]

can_prepare abstractmethod async

can_prepare(command: CommandT, *, context: PreparationContext) -> AuthorizationResult

can_decide abstractmethod async

can_decide(evidence: AuthorityEvidence, *, context: DecisionContext) -> AuthorizationResult

can_execute abstractmethod async

can_execute(snapshot: PrivateSnapshotT, *, context: ExecutionContext) -> AuthorizationResult

can_read abstractmethod async

can_read(proposal_reference: str, *, context: ReadContext) -> bool

resolve abstractmethod async

resolve(snapshot: PrivateSnapshotT, *, context: ExecutionContext) -> ResolvedState[PrivateSnapshotT, PreviewT]

execute abstractmethod async

execute(snapshot: PrivateSnapshotT, *, context: ExecutionContext, execution_precondition: str) -> ExecutionResult[ResultT]

verify abstractmethod async

verify(*, context: ExecutionContext) -> VerificationResult[ResultT]

authorize_erasure async

authorize_erasure(proposal_reference: str, *, context: ReadContext) -> bool

ActionConfigurationError

Bases: TypeError

Raised when an Action subclass cannot compile to ActionDefinition.

AnyApproval dataclass

AnyApproval(authorities: tuple[ConfirmingAuthority, ...])

Require one distinct authority from a declared set.

authorities instance-attribute

authorities: tuple[ConfirmingAuthority, ...]

__post_init__

__post_init__() -> None

evaluate async

evaluate(*, binding: AuthorityBinding, evidence: tuple[AuthorityEvidence, ...]) -> AuthorityEvaluation

ApprovalReasonCode

Bases: StrEnum

Reason codes generated by the evidence-only approval requirements.

MORE_AUTHORITY_REQUIRED class-attribute instance-attribute

MORE_AUTHORITY_REQUIRED = 'more_authority_required'

MOfNApprovals dataclass

MOfNApprovals(required: int, authorities: tuple[ConfirmingAuthority, ...])

Require approvals from a distinct M-of-N set of authorities.

required instance-attribute

required: int

authorities instance-attribute

authorities: tuple[ConfirmingAuthority, ...]

__post_init__

__post_init__() -> None

evaluate async

evaluate(*, binding: AuthorityBinding, evidence: tuple[AuthorityEvidence, ...]) -> AuthorityEvaluation

SingleApproval dataclass

SingleApproval(authority: ConfirmingAuthority)

Require one specific authority after the host authorizes the decision.

authority instance-attribute

authority: ConfirmingAuthority

evaluate async

evaluate(*, binding: AuthorityBinding, evidence: tuple[AuthorityEvidence, ...]) -> AuthorityEvaluation

RuntimeAttributionError

Bases: RuntimeError

The runtime cannot identify the exact library code producing receipts.

AuthorityBinding

Bases: ExperimentalModel

Security-relevant dimensions an authority record must match exactly.

tenant_reference instance-attribute

tenant_reference: SafeReference

action_type instance-attribute

action_type: ActionType

proposal_instance_reference instance-attribute

proposal_instance_reference: SafeReference

semantic_effect_reference instance-attribute

semantic_effect_reference: SafeReference

proposal_commitment instance-attribute

proposal_commitment: SafeReference

required_audience instance-attribute

required_audience: SafeReference

required_channel_assurance instance-attribute

required_channel_assurance: SafeReference

AuthorityDecision

Bases: StrEnum

APPROVE class-attribute instance-attribute

APPROVE = 'approve'

REJECT class-attribute instance-attribute

REJECT = 'reject'

AuthorityEvidence

Bases: ExperimentalModel

A bound authority decision; it is not authorization by itself.

kind class-attribute instance-attribute

kind: Literal['bound_decision'] = 'bound_decision'

domain class-attribute instance-attribute

domain: Literal['threvo.actions.authority-evidence'] = 'threvo.actions.authority-evidence'

schema_version class-attribute instance-attribute

schema_version: Literal['internal/v0'] = 'internal/v0'

tenant_reference instance-attribute

tenant_reference: SafeReference

action_type instance-attribute

action_type: ActionType

proposal_instance_reference instance-attribute

proposal_instance_reference: SafeReference

semantic_effect_reference instance-attribute

semantic_effect_reference: SafeReference

authority instance-attribute

authority: ConfirmingAuthority

audience class-attribute instance-attribute

audience: tuple[SafeReference, ...] = Field(min_length=1)

decision instance-attribute

decision: AuthorityDecision

proposal_commitment instance-attribute

proposal_commitment: SafeReference

channel_assurance instance-attribute

channel_assurance: SafeReference

issued_at instance-attribute

issued_at: AwareDatetime

expires_at instance-attribute

expires_at: AwareDatetime

expiry_follows_issue_time

expiry_follows_issue_time() -> AuthorityEvidence

AuthorityValidationFailure

Bases: StrEnum

BINDING_MISMATCH class-attribute instance-attribute

BINDING_MISMATCH = 'binding_mismatch'

EXPIRED class-attribute instance-attribute

EXPIRED = 'expired'

NOT_YET_VALID class-attribute instance-attribute

NOT_YET_VALID = 'not_yet_valid'

AuthorityValidationResult

Bases: ExperimentalModel

valid instance-attribute

valid: bool

failure class-attribute instance-attribute

failure: AuthorityValidationFailure | None = None

CanonicalizationError

Bases: ValueError

Raised when a value cannot enter the canonical finance boundary.

CommitmentProvider

Bases: Protocol

Host-owned proposal-scoped keyed commitment boundary.

Destruction must be idempotent so an interrupted erasure can resume safely.

create async

create(*, proposal_reference: str, canonical_payload: bytes) -> KeyedCommitment

verify async

verify(*, proposal_reference: str, canonical_payload: bytes, commitment: KeyedCommitment) -> bool

destroy_commitment async

destroy_commitment(*, commitment: KeyedCommitment) -> None

KeyedCommitment

Bases: ExperimentalModel

Opaque commitment metadata; key material remains with the host.

algorithm instance-attribute

algorithm: str

key_handle instance-attribute

key_handle: SafeReference

key_version instance-attribute

key_version: SafeReference

digest instance-attribute

digest: SafeReference

ProtectedPayload

Bases: ExperimentalModel

A private snapshot protected before it reaches an action store.

codec instance-attribute

codec: SafeReference

key_handle instance-attribute

key_handle: SafeReference

key_version instance-attribute

key_version: SafeReference

ciphertext instance-attribute

ciphertext: OpaquePayload

ProtectionCodec

Bases: Protocol

Host-owned protection boundary for canonical private snapshots.

Destruction must be idempotent so an interrupted erasure can resume safely.

protect async

protect(*, proposal_reference: str, canonical_payload: bytes) -> ProtectedPayload

unprotect async

unprotect(*, payload: ProtectedPayload) -> bytes

destroy_payload async

destroy_payload(*, payload: ProtectedPayload) -> None

ActionType

Bases: ExperimentalModel

A host-defined action name with an explicit contract version.

namespace instance-attribute

namespace: ActionNamespace

name instance-attribute

name: ActionName

version instance-attribute

version: Annotated[int, Field(ge=1)]

AuthoritativeTarget

Bases: ExperimentalModel

kind class-attribute instance-attribute

kind: Literal['authoritative_target'] = 'authoritative_target'

reference instance-attribute

reference: SafeReference

ConfirmingAuthority

Bases: ExperimentalModel

kind class-attribute instance-attribute

kind: Literal['confirming_authority'] = 'confirming_authority'

reference instance-attribute

reference: SafeReference

EvidenceConsumer

Bases: ExperimentalModel

kind class-attribute instance-attribute

kind: Literal['evidence_consumer'] = 'evidence_consumer'

reference instance-attribute

reference: SafeReference

GovernedExecutor

Bases: ExperimentalModel

kind class-attribute instance-attribute

kind: Literal['governed_executor'] = 'governed_executor'

reference instance-attribute

reference: SafeReference

LifecycleStatus

Bases: StrEnum

Closed lifecycle vocabulary for proposal execution and verification.

AWAITING_AUTHORITY class-attribute instance-attribute

AWAITING_AUTHORITY = 'awaiting_authority'

DENIED class-attribute instance-attribute

DENIED = 'denied'

EXPIRED class-attribute instance-attribute

EXPIRED = 'expired'

AUTHORIZED class-attribute instance-attribute

AUTHORIZED = 'authorized'

BLOCKED class-attribute instance-attribute

BLOCKED = 'blocked'

STALE class-attribute instance-attribute

STALE = 'stale'

SUPERSEDED class-attribute instance-attribute

SUPERSEDED = 'superseded'

EXECUTING class-attribute instance-attribute

EXECUTING = 'executing'

FAILED_KNOWN class-attribute instance-attribute

FAILED_KNOWN = 'failed_known'

FAILED_UNKNOWN class-attribute instance-attribute

FAILED_UNKNOWN = 'failed_unknown'

VERIFICATION_PENDING class-attribute instance-attribute

VERIFICATION_PENDING = 'verification_pending'

VERIFICATION_UNRESOLVED class-attribute instance-attribute

VERIFICATION_UNRESOLVED = 'verification_unresolved'

PARTIALLY_SUCCEEDED class-attribute instance-attribute

PARTIALLY_SUCCEEDED = 'partially_succeeded'

VERIFIED class-attribute instance-attribute

VERIFIED = 'verified'

Money

Bases: ExperimentalModel

A monetary amount whose currency is explicit and precision is host-validated.

amount instance-attribute

amount: Annotated[Decimal, Field(max_digits=28)]

currency instance-attribute

currency: CurrencyCode

ProposingAgent

Bases: ExperimentalModel

kind class-attribute instance-attribute

kind: Literal['proposing_agent'] = 'proposing_agent'

reference instance-attribute

reference: SafeReference

RequestingPrincipal

Bases: ExperimentalModel

kind class-attribute instance-attribute

kind: Literal['requesting_principal'] = 'requesting_principal'

reference instance-attribute

reference: SafeReference

AuthorityReceipt

Bases: _ReceiptBase

receipt_type class-attribute instance-attribute

receipt_type: Literal['authority'] = 'authority'

status instance-attribute

status: AuthorityReceiptStatus

participant instance-attribute

participant: ConfirmingAuthority

AuthorityReceiptStatus

Bases: StrEnum

RECORDED class-attribute instance-attribute

RECORDED = 'recorded'

REJECTED class-attribute instance-attribute

REJECTED = 'rejected'

FAILED class-attribute instance-attribute

FAILED = 'failed'

MISSING class-attribute instance-attribute

MISSING = 'missing'

EventSink

Bases: Protocol

Best-effort, at-most-once projection called after durable state changes.

emit async

emit(event: RuntimeEvent) -> None

ExecutionReceipt

Bases: _ReceiptBase

receipt_type class-attribute instance-attribute

receipt_type: Literal['execution'] = 'execution'

status instance-attribute

status: ExecutionReceiptStatus

participant instance-attribute

participant: GovernedExecutor

item_outcomes class-attribute instance-attribute

item_outcomes: tuple[ItemOutcome, ...] = ()

ExecutionReceiptStatus

Bases: StrEnum

STARTED class-attribute instance-attribute

STARTED = 'started'

ACCEPTED class-attribute instance-attribute

ACCEPTED = 'accepted'

PARTIALLY_SUCCEEDED class-attribute instance-attribute

PARTIALLY_SUCCEEDED = 'partially_succeeded'

STALE_NO_EFFECT class-attribute instance-attribute

STALE_NO_EFFECT = 'stale_no_effect'

FAILED_KNOWN class-attribute instance-attribute

FAILED_KNOWN = 'failed_known'

FAILED_UNKNOWN class-attribute instance-attribute

FAILED_UNKNOWN = 'failed_unknown'

MISSING class-attribute instance-attribute

MISSING = 'missing'

ExternalReference

Bases: ExperimentalModel

A minimized provider reference safe for an evidence projection.

system instance-attribute

system: SafeReference

reference instance-attribute

reference: SafeReference

ItemOutcome

Bases: ExperimentalModel

A minimized authoritative outcome for one declared itemized effect.

item_reference instance-attribute

item_reference: SafeReference

status instance-attribute

status: ItemOutcomeStatus

reason_code class-attribute instance-attribute

reason_code: SafeReference | None = None

ItemOutcomeStatus

Bases: StrEnum

SUCCEEDED class-attribute instance-attribute

SUCCEEDED = 'succeeded'

FAILED_KNOWN class-attribute instance-attribute

FAILED_KNOWN = 'failed_known'

FAILED_UNKNOWN class-attribute instance-attribute

FAILED_UNKNOWN = 'failed_unknown'

NoopEventSink

emit async

emit(event: RuntimeEvent) -> None

ProposalReceipt

Bases: _ReceiptBase

receipt_type class-attribute instance-attribute

receipt_type: Literal['proposal'] = 'proposal'

status instance-attribute

status: ProposalReceiptStatus

requesting_principal instance-attribute

requesting_principal: RequestingPrincipal

proposing_agent class-attribute instance-attribute

proposing_agent: ProposingAgent | None = None

ProposalReceiptStatus

Bases: StrEnum

PREPARED class-attribute instance-attribute

PREPARED = 'prepared'

FAILED class-attribute instance-attribute

FAILED = 'failed'

MISSING class-attribute instance-attribute

MISSING = 'missing'

RuntimeEvent

Bases: ExperimentalModel

Allowlisted event metadata; snapshots and result payloads are impossible.

event_type instance-attribute

event_type: RuntimeEventType

tenant_reference instance-attribute

tenant_reference: SafeReference

proposal_reference instance-attribute

proposal_reference: SafeReference

action_type instance-attribute

action_type: ActionType

lifecycle_status instance-attribute

lifecycle_status: LifecycleStatus

correlation_reference instance-attribute

correlation_reference: SafeReference

observed_at instance-attribute

observed_at: AwareDatetime

reason_code class-attribute instance-attribute

reason_code: SafeReference | None = None

RuntimeEventType

Bases: StrEnum

PROPOSAL_PREPARED class-attribute instance-attribute

PROPOSAL_PREPARED = 'proposal_prepared'

AUTHORITY_RECORDED class-attribute instance-attribute

AUTHORITY_RECORDED = 'authority_recorded'

LIFECYCLE_CHANGED class-attribute instance-attribute

LIFECYCLE_CHANGED = 'lifecycle_changed'

VERIFICATION_OBSERVED class-attribute instance-attribute

VERIFICATION_OBSERVED = 'verification_observed'

PROPOSAL_ERASED class-attribute instance-attribute

PROPOSAL_ERASED = 'proposal_erased'

VerificationReceipt

Bases: _ReceiptBase

receipt_type class-attribute instance-attribute

receipt_type: Literal['verification'] = 'verification'

status instance-attribute

status: VerificationReceiptStatus

participant instance-attribute

participant: AuthoritativeTarget

item_outcomes class-attribute instance-attribute

item_outcomes: tuple[ItemOutcome, ...] = ()

VerificationReceiptStatus

Bases: StrEnum

VERIFIED_COMPLETION class-attribute instance-attribute

VERIFIED_COMPLETION = 'verified_completion'

VERIFIED_TERMINAL_FAILURE class-attribute instance-attribute

VERIFIED_TERMINAL_FAILURE = 'verified_terminal_failure'

PROVISIONAL_ABSENCE class-attribute instance-attribute

PROVISIONAL_ABSENCE = 'provisional_absence'

AUTHORITATIVE_FINAL_ABSENCE class-attribute instance-attribute

AUTHORITATIVE_FINAL_ABSENCE = 'authoritative_final_absence'

TARGET_UNAVAILABLE class-attribute instance-attribute

TARGET_UNAVAILABLE = 'target_unavailable'

VERIFICATION_UNRESOLVED class-attribute instance-attribute

VERIFICATION_UNRESOLVED = 'verification_unresolved'

MISSING class-attribute instance-attribute

MISSING = 'missing'

ActionDefinition dataclass

ActionDefinition(action_type: ActionType, command_model: type[CommandT], private_snapshot_model: type[PrivateSnapshotT], display_preview_model: type[PreviewT], result_model: type[ResultT], preparation: PreparationPort[CommandT, PrivateSnapshotT, PreviewT], authorization: AuthorizationPort[CommandT, PrivateSnapshotT], authority_evaluator: AuthorityEvaluatorPort, state_resolver: StateResolverPort[PrivateSnapshotT, PreviewT], executor: GovernedExecutorPort[PrivateSnapshotT, ResultT], verifier: VerifierPort[ResultT], commitment_provider: CommitmentProvider, protection_codec: ProtectionCodec, retention: RetentionPort, proposal_ttl: timedelta, executor_identity: GovernedExecutor, target_identity: AuthoritativeTarget, authority_audience: str, authority_channel_assurance: str, verification_delay: timedelta = timedelta(0), max_verification_attempts: int = 3, effect_kind: EffectKind = 'single', allow_resend_after_final_absence: bool = False, verification_lease_duration: timedelta = timedelta(minutes=1), semantic_idempotency_strategy: Literal['host_defined'] = 'host_defined')

Bases: Generic[CommandT, PrivateSnapshotT, PreviewT, ResultT]

action_type instance-attribute

action_type: ActionType

command_model instance-attribute

command_model: type[CommandT]

private_snapshot_model instance-attribute

private_snapshot_model: type[PrivateSnapshotT]

display_preview_model instance-attribute

display_preview_model: type[PreviewT]

result_model instance-attribute

result_model: type[ResultT]

preparation instance-attribute

preparation: PreparationPort[CommandT, PrivateSnapshotT, PreviewT]

authorization instance-attribute

authorization: AuthorizationPort[CommandT, PrivateSnapshotT]

authority_evaluator instance-attribute

authority_evaluator: AuthorityEvaluatorPort

state_resolver instance-attribute

state_resolver: StateResolverPort[PrivateSnapshotT, PreviewT]

executor instance-attribute

executor: GovernedExecutorPort[PrivateSnapshotT, ResultT]

verifier instance-attribute

verifier: VerifierPort[ResultT]

commitment_provider instance-attribute

commitment_provider: CommitmentProvider

protection_codec instance-attribute

protection_codec: ProtectionCodec

retention instance-attribute

retention: RetentionPort

proposal_ttl instance-attribute

proposal_ttl: timedelta

executor_identity instance-attribute

executor_identity: GovernedExecutor

target_identity instance-attribute

target_identity: AuthoritativeTarget

authority_audience instance-attribute

authority_audience: str

authority_channel_assurance instance-attribute

authority_channel_assurance: str

verification_delay class-attribute instance-attribute

verification_delay: timedelta = timedelta(0)

max_verification_attempts class-attribute instance-attribute

max_verification_attempts: int = 3

effect_kind class-attribute instance-attribute

effect_kind: EffectKind = 'single'

allow_resend_after_final_absence class-attribute instance-attribute

allow_resend_after_final_absence: bool = False

verification_lease_duration class-attribute instance-attribute

verification_lease_duration: timedelta = timedelta(minutes=1)

semantic_idempotency_strategy class-attribute instance-attribute

semantic_idempotency_strategy: Literal['host_defined'] = 'host_defined'

__post_init__

__post_init__() -> None

ActionNotRegisteredError

Bases: LookupError

ActionRegistry

ActionRegistry()

A heterogeneous registry with checked type recovery at its boundary.

register

register(definition: ActionDefinition[CommandT, PrivateSnapshotT, PreviewT, ResultT]) -> None

get_typed

get_typed(action_type: ActionType, *, command_model: type[CommandT], private_snapshot_model: type[PrivateSnapshotT], display_preview_model: type[PreviewT], result_model: type[ResultT]) -> ActionDefinition[CommandT, PrivateSnapshotT, PreviewT, ResultT]

AuthorityEvaluation

Bases: ExperimentalModel

satisfied instance-attribute

satisfied: bool

reason_code class-attribute instance-attribute

reason_code: SafeReference | None = None

AuthorityEvaluatorPort

Bases: Protocol

evaluate async

evaluate(*, binding: AuthorityBinding, evidence: tuple[AuthorityEvidence, ...]) -> AuthorityEvaluation

AuthorizationPort

Bases: Protocol[CommandContraT, PrivateContraT]

can_prepare async

can_prepare(command: CommandContraT, *, context: PreparationContext) -> AuthorizationResult

can_decide async

can_decide(evidence: AuthorityEvidence, *, context: DecisionContext) -> AuthorizationResult

can_execute async

can_execute(snapshot: PrivateContraT, *, context: ExecutionContext) -> AuthorizationResult

can_read async

can_read(proposal_reference: str, *, context: ReadContext) -> bool

AuthorizationResult

Bases: ExperimentalModel

allowed instance-attribute

allowed: bool

reason_code class-attribute instance-attribute

reason_code: SafeReference | None = None

DecisionContext

Bases: ExperimentalModel

tenant_reference instance-attribute

tenant_reference: SafeReference

authority instance-attribute

authority: ConfirmingAuthority

decided_at instance-attribute

decided_at: AwareDatetime

DefinitionConformanceError

Bases: ValueError

Raised when declared boundary models cannot satisfy the runtime contract.

DefinitionTypeMismatchError

Bases: TypeError

DuplicateActionError

Bases: RuntimeError

ExecutionContext

Bases: ExperimentalModel

tenant_reference instance-attribute

tenant_reference: SafeReference

proposal_reference instance-attribute

proposal_reference: SafeReference

semantic_effect_reference instance-attribute

semantic_effect_reference: SafeReference

requesting_principal instance-attribute

requesting_principal: RequestingPrincipal

authorities instance-attribute

authorities: tuple[ConfirmingAuthority, ...]

observed_at instance-attribute

observed_at: AwareDatetime

ExecutionResult

Bases: ExperimentalModel, Generic[ResultT]

status instance-attribute

status: ExecutionStatus

result class-attribute instance-attribute

result: ResultT | None = None

item_outcomes class-attribute instance-attribute

item_outcomes: tuple[ItemOutcome, ...] = ()

external_reference class-attribute instance-attribute

external_reference: ExternalReference | None = None

reason_code class-attribute instance-attribute

reason_code: SafeReference | None = None

partial_requires_items

partial_requires_items() -> ExecutionResult[ResultT]

ExecutionStatus

Bases: StrEnum

ACCEPTED class-attribute instance-attribute

ACCEPTED = 'accepted'

STALE_NO_EFFECT class-attribute instance-attribute

STALE_NO_EFFECT = 'stale_no_effect'

FAILED_KNOWN class-attribute instance-attribute

FAILED_KNOWN = 'failed_known'

FAILED_UNKNOWN class-attribute instance-attribute

FAILED_UNKNOWN = 'failed_unknown'

PARTIALLY_SUCCEEDED class-attribute instance-attribute

PARTIALLY_SUCCEEDED = 'partially_succeeded'

GovernedExecutorPort

Bases: Protocol[PrivateContraT, ResultT]

execute async

execute(snapshot: PrivateContraT, *, context: ExecutionContext, execution_precondition: str) -> ExecutionResult[ResultT]

PreparationContext

Bases: ExperimentalModel

tenant_reference instance-attribute

tenant_reference: SafeReference

requesting_principal instance-attribute

requesting_principal: RequestingPrincipal

proposing_agent class-attribute instance-attribute

proposing_agent: ProposingAgent | None = None

prepared_at instance-attribute

prepared_at: AwareDatetime

PreparationPort

Bases: Protocol[CommandContraT, PrivateSnapshotT, PreviewT]

prepare async

prepare(command: CommandContraT, *, context: PreparationContext) -> PreparedAction[PrivateSnapshotT, PreviewT]

PreparedAction dataclass

PreparedAction(private_snapshot: PrivateSnapshotT, display_preview: PreviewT, semantic_effect_reference: str)

Bases: Generic[PrivateSnapshotT, PreviewT]

private_snapshot instance-attribute

private_snapshot: PrivateSnapshotT

display_preview instance-attribute

display_preview: PreviewT

semantic_effect_reference instance-attribute

semantic_effect_reference: str

__post_init__

__post_init__() -> None

ReadContext

Bases: ExperimentalModel

tenant_reference instance-attribute

tenant_reference: SafeReference

consumer instance-attribute

consumer: EvidenceConsumer

ResolvedState dataclass

ResolvedState(current_snapshot: PrivateSnapshotT, execution_precondition: str, materially_drifted: bool, replacement: PreparedAction[PrivateSnapshotT, PreviewT] | None = None)

Bases: Generic[PrivateSnapshotT, PreviewT]

current_snapshot instance-attribute

current_snapshot: PrivateSnapshotT

execution_precondition instance-attribute

execution_precondition: str

materially_drifted instance-attribute

materially_drifted: bool

replacement class-attribute instance-attribute

replacement: PreparedAction[PrivateSnapshotT, PreviewT] | None = None

__post_init__

__post_init__() -> None

RetentionPort

Bases: Protocol

authorize_erasure async

authorize_erasure(proposal_reference: str, *, context: ReadContext) -> bool

StateResolverPort

Bases: Protocol[PrivateSnapshotT, PreviewT]

resolve async

resolve(snapshot: PrivateSnapshotT, *, context: ExecutionContext) -> ResolvedState[PrivateSnapshotT, PreviewT]

VerificationResult

Bases: ExperimentalModel, Generic[ResultT]

status instance-attribute

status: VerificationStatus

result class-attribute instance-attribute

result: ResultT | None = None

item_outcomes class-attribute instance-attribute

item_outcomes: tuple[ItemOutcome, ...] = ()

external_reference class-attribute instance-attribute

external_reference: ExternalReference | None = None

reason_code class-attribute instance-attribute

reason_code: SafeReference | None = None

settling_boundary_passed class-attribute instance-attribute

settling_boundary_passed: bool = False

target_idempotency_guaranteed class-attribute instance-attribute

target_idempotency_guaranteed: bool = False

absence_requires_consistent_evidence

absence_requires_consistent_evidence() -> VerificationResult[ResultT]

VerificationStatus

Bases: StrEnum

VERIFIED_COMPLETION class-attribute instance-attribute

VERIFIED_COMPLETION = 'verified_completion'

VERIFIED_TERMINAL_FAILURE class-attribute instance-attribute

VERIFIED_TERMINAL_FAILURE = 'verified_terminal_failure'

PROVISIONAL_ABSENCE class-attribute instance-attribute

PROVISIONAL_ABSENCE = 'provisional_absence'

AUTHORITATIVE_FINAL_ABSENCE class-attribute instance-attribute

AUTHORITATIVE_FINAL_ABSENCE = 'authoritative_final_absence'

TARGET_UNAVAILABLE class-attribute instance-attribute

TARGET_UNAVAILABLE = 'target_unavailable'

VerifierPort

Bases: Protocol[ResultT]

verify async

verify(*, context: ExecutionContext) -> VerificationResult[ResultT]

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.

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

AuthorizationDeniedError

Bases: PermissionError

Clock

Bases: Protocol

now

now() -> datetime

IdentifierProvider

Bases: Protocol

new

new(prefix: str) -> str

InvalidActionResultError

Bases: RuntimeError

InvalidAuthorityEvidenceError

Bases: ValueError

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'

ProposalNotFoundError

ProposalNotFoundError()

Bases: LookupError

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

RetentionStoreUnavailableError

Bases: RuntimeError

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'

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

ActionStore

Bases: Protocol

create async

create(proposal: StoredProposal) -> None

get async

get(tenant_reference: str, proposal_reference: str) -> StoredProposal | None

compare_and_set async

compare_and_set(*, tenant_reference: str, proposal_reference: str, expected_revision: int, expected_statuses: tuple[LifecycleStatus, ...], updated: StoredProposal) -> bool

admit_execution async

admit_execution(*, tenant_reference: str, proposal_reference: str, expected_revision: int, admitted_at: datetime, updated: StoredProposal) -> EffectClaimResult

get_effect_claim_owner async

get_effect_claim_owner(*, tenant_reference: str, action_type: ActionType, semantic_effect_reference: str) -> str | None

EffectClaimResult

Bases: StrEnum

ACQUIRED class-attribute instance-attribute

ACQUIRED = 'acquired'

OWNED_BY_PROPOSAL class-attribute instance-attribute

OWNED_BY_PROPOSAL = 'owned_by_proposal'

CONFLICT class-attribute instance-attribute

CONFLICT = 'conflict'

PROPOSAL_NOT_FOUND class-attribute instance-attribute

PROPOSAL_NOT_FOUND = 'proposal_not_found'

PROPOSAL_NOT_AUTHORIZED class-attribute instance-attribute

PROPOSAL_NOT_AUTHORIZED = 'proposal_not_authorized'

MemoryActionStore

MemoryActionStore()

Bases: ActionStore, RetentionStore

An in-process conformance store with tenant-scoped guarded writes.

create async

create(proposal: StoredProposal) -> None

get async

get(tenant_reference: str, proposal_reference: str) -> StoredProposal | None

compare_and_set async

compare_and_set(*, tenant_reference: str, proposal_reference: str, expected_revision: int, expected_statuses: tuple[LifecycleStatus, ...], updated: StoredProposal) -> bool

admit_execution async

admit_execution(*, tenant_reference: str, proposal_reference: str, expected_revision: int, admitted_at: datetime, updated: StoredProposal) -> EffectClaimResult

get_effect_claim_owner async

get_effect_claim_owner(*, tenant_reference: str, action_type: ActionType, semantic_effect_reference: str) -> str | None

mark_erasure_pending async

mark_erasure_pending(*, tenant_reference: str, proposal_reference: str, expected_revision: int, pending_at: datetime) -> bool

complete_erasure async

complete_erasure(*, tenant_reference: str, proposal_reference: str, expected_revision: int, erased_at: datetime) -> bool

ProposalAlreadyExistsError

Bases: RuntimeError

RetentionStore

Bases: Protocol

Privileged persistence operations kept outside the runtime DB role.

mark_erasure_pending async

mark_erasure_pending(*, tenant_reference: str, proposal_reference: str, expected_revision: int, pending_at: datetime) -> bool

complete_erasure async

complete_erasure(*, tenant_reference: str, proposal_reference: str, expected_revision: int, erased_at: datetime) -> bool

StoredProposal

Bases: ExperimentalModel

Persistence-neutral lifecycle record; private state is always protected.

tenant_reference instance-attribute

tenant_reference: SafeReference

proposal_reference instance-attribute

proposal_reference: SafeReference

action_type instance-attribute

action_type: ActionType

semantic_effect_reference instance-attribute

semantic_effect_reference: SafeReference

effect_kind instance-attribute

effect_kind: EffectKind

lifecycle_status instance-attribute

lifecycle_status: LifecycleStatus

revision class-attribute instance-attribute

revision: int = Field(ge=0)

protected_private_snapshot instance-attribute

protected_private_snapshot: ProtectedPayload | None

commitment instance-attribute

commitment: KeyedCommitment | None

display_preview class-attribute instance-attribute

display_preview: JsonObject = Field(default_factory=dict)

requesting_principal class-attribute instance-attribute

requesting_principal: RequestingPrincipal | None = None

proposing_agent class-attribute instance-attribute

proposing_agent: ProposingAgent | None = None

created_at instance-attribute

created_at: AwareDatetime

expires_at instance-attribute

expires_at: AwareDatetime

authority_evidence class-attribute instance-attribute

authority_evidence: tuple[AuthorityEvidence, ...] = ()

receipts class-attribute instance-attribute

receipts: tuple[Receipt, ...] = ()

verification_attempts class-attribute instance-attribute

verification_attempts: int = Field(default=0, ge=0)

max_verification_attempts class-attribute instance-attribute

max_verification_attempts: int = Field(ge=1)

next_verification_at class-attribute instance-attribute

next_verification_at: AwareDatetime | None = None

safe_result class-attribute instance-attribute

safe_result: JsonObject | None = None

execution_precondition class-attribute instance-attribute

execution_precondition: SafeReference | None = None

superseded_by class-attribute instance-attribute

superseded_by: SafeReference | None = None

erasure_pending_at class-attribute instance-attribute

erasure_pending_at: AwareDatetime | None = None

erased_at class-attribute instance-attribute

erased_at: AwareDatetime | None = None

StoreInvariantError

Bases: RuntimeError

resolve_runtime_revision

resolve_runtime_revision(*, package_root: Path | None = None) -> str

Return an exact released version or source commit plus package-tree digest.

authority_evidence_matches_binding

authority_evidence_matches_binding(evidence: AuthorityEvidence, *, binding: AuthorityBinding) -> bool

Check proposal binding dimensions without evaluating time or sufficiency.

validate_authority_evidence

validate_authority_evidence(evidence: AuthorityEvidence, *, binding: AuthorityBinding, now: AwareDatetime) -> AuthorityValidationResult

Validate server-bound evidence without treating it as sufficient policy.

canonicalize_v1

canonicalize_v1(document: JsonValue) -> bytes

Produce deterministic UTF-8 JSON for the internal canonical v1 profile.

commitment_payload_v1

commitment_payload_v1(*, proposal_reference: str, canonical_payload: bytes) -> bytes

Domain-separate a private snapshot commitment from every other digest.

assert_definition_conforms

assert_definition_conforms(definition: ActionDefinition[CommandT, PrivateSnapshotT, PreviewT, ResultT]) -> None

Reject declared model shapes that cannot satisfy the runtime boundary.

validate_proposal_create

validate_proposal_create(proposal: StoredProposal) -> None

validate_proposal_update

validate_proposal_update(*, current: StoredProposal, updated: StoredProposal) -> None