Receipts and events

receipts

Experimental typed lifecycle evidence models.

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

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

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)

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'

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

ProposalReceiptStatus

Bases: StrEnum

PREPARED class-attribute instance-attribute

PREPARED = 'prepared'

FAILED class-attribute instance-attribute

FAILED = 'failed'

MISSING class-attribute instance-attribute

MISSING = 'missing'

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'

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'

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'

ExternalReference

Bases: ExperimentalModel

A minimized provider reference safe for an evidence projection.

system instance-attribute

system: SafeReference

reference instance-attribute

reference: SafeReference

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'

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

_ReceiptBase

Bases: ExperimentalModel

schema_version class-attribute instance-attribute

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

receipt_reference instance-attribute

receipt_reference: SafeReference

correlation_reference instance-attribute

correlation_reference: SafeReference

causation_reference instance-attribute

causation_reference: SafeReference

observed_at instance-attribute

observed_at: AwareDatetime

runtime_revision class-attribute instance-attribute

runtime_revision: SafeReference | None = None

external_reference class-attribute instance-attribute

external_reference: ExternalReference | None = None

corrects_receipt_reference class-attribute instance-attribute

corrects_receipt_reference: SafeReference | None = None

supersedes_receipt_reference class-attribute instance-attribute

supersedes_receipt_reference: SafeReference | None = None

reason_code class-attribute instance-attribute

reason_code: SafeReference | None = 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

AuthorityReceipt

Bases: _ReceiptBase

receipt_type class-attribute instance-attribute

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

status instance-attribute

status: AuthorityReceiptStatus

participant instance-attribute

participant: ConfirmingAuthority

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, ...] = ()

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, ...] = ()

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'

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

EventSink

Bases: Protocol

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

emit async

emit(event: RuntimeEvent) -> None

NoopEventSink

emit async

emit(event: RuntimeEvent) -> None