Canonicalization and protection

canonical

Versioned canonical JSON and protected-payload ports.

SafeReference module-attribute

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

JsonObject module-attribute

JsonObject = dict[str, JsonValue]

OpaquePayload module-attribute

OpaquePayload = Annotated[str, StringConstraints(min_length=1, max_length=1048576)]

_JSON_OBJECT_ADAPTER module-attribute

_JSON_OBJECT_ADAPTER = TypeAdapter(JsonObject)

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)

CanonicalizationError

Bases: ValueError

Raised when a value cannot enter the canonical finance boundary.

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

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

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

model_json_object

model_json_object(model: BaseModel) -> JsonObject

Convert a host Pydantic model to a checked JSON object.

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.

_normalize

_normalize(value: JsonValue) -> JsonValue