Stores

Store contracts

base

Tenant-scoped persistence contract for the action lifecycle.

EffectKind module-attribute

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

SafeReference module-attribute

SafeReference = Annotated[str, StringConstraints(min_length=1, max_length=255), AfterValidator(_validate_safe_reference)]

Receipt module-attribute

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

JsonObject module-attribute

JsonObject = dict[str, JsonValue]

ALLOWED_LIFECYCLE_TRANSITIONS module-attribute

ALLOWED_LIFECYCLE_TRANSITIONS: dict[LifecycleStatus, frozenset[LifecycleStatus]] = {LifecycleStatus.AWAITING_AUTHORITY: frozenset({LifecycleStatus.AUTHORIZED, LifecycleStatus.DENIED, LifecycleStatus.EXPIRED}), LifecycleStatus.AUTHORIZED: frozenset({LifecycleStatus.BLOCKED, LifecycleStatus.EXPIRED, LifecycleStatus.EXECUTING, LifecycleStatus.STALE}), LifecycleStatus.EXECUTING: frozenset({LifecycleStatus.STALE, LifecycleStatus.FAILED_KNOWN, LifecycleStatus.FAILED_UNKNOWN, LifecycleStatus.VERIFICATION_PENDING}), LifecycleStatus.FAILED_UNKNOWN: frozenset({LifecycleStatus.VERIFICATION_PENDING}), LifecycleStatus.VERIFICATION_PENDING: frozenset({LifecycleStatus.AUTHORIZED, LifecycleStatus.EXECUTING, LifecycleStatus.FAILED_KNOWN, LifecycleStatus.FAILED_UNKNOWN, LifecycleStatus.PARTIALLY_SUCCEEDED, LifecycleStatus.VERIFICATION_UNRESOLVED, LifecycleStatus.VERIFIED}), LifecycleStatus.STALE: frozenset({LifecycleStatus.SUPERSEDED}), LifecycleStatus.VERIFIED: frozenset(), LifecycleStatus.BLOCKED: frozenset(), LifecycleStatus.DENIED: frozenset(), LifecycleStatus.EXPIRED: frozenset(), LifecycleStatus.FAILED_KNOWN: frozenset(), LifecycleStatus.PARTIALLY_SUCCEEDED: frozenset(), LifecycleStatus.SUPERSEDED: frozenset(), LifecycleStatus.VERIFICATION_UNRESOLVED: frozenset()}

ERASABLE_LIFECYCLE_STATUSES module-attribute

ERASABLE_LIFECYCLE_STATUSES = frozenset(status for status in LifecycleStatus if status not in {LifecycleStatus.EXECUTING, LifecycleStatus.FAILED_UNKNOWN, LifecycleStatus.VERIFICATION_PENDING})

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

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

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

ExperimentalModel

Bases: BaseModel

Strict, immutable base for the experimental public contract.

model_config class-attribute instance-attribute

model_config = ConfigDict(extra='forbid', strict=True, frozen=True)

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'

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

ProposalAlreadyExistsError

Bases: RuntimeError

StoreInvariantError

Bases: RuntimeError

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'

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

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

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

validate_proposal_create

validate_proposal_create(proposal: StoredProposal) -> None

proposal_with_erasure_pending

proposal_with_erasure_pending(proposal: StoredProposal, *, pending_at: datetime) -> StoredProposal

erased_proposal

erased_proposal(proposal: StoredProposal, *, erased_at: datetime) -> StoredProposal

validate_proposal_update

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

_validate_proposal_bindings

_validate_proposal_bindings(proposal: StoredProposal) -> None

In-memory store

memory

Concurrency-correct in-memory implementation of :mod:stores.base.

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

The durable adapters are documented in PostgreSQL and migrations and SQLite and migrations. Use Build a custom action store for another database.