Skip to main content

qualia_app_contract/
lib.rs

1//! # Qualia Application Contract
2//!
3//! Canonical portable command, context, session, and surface contracts for
4//! Storytold applications, Poet, and Webizen OS.
5//!
6//! Aligned with POET Implementation Plan ST-E, ST-G, and ST-H.
7//!
8//! Copyright (c) 2026 Timothy Charles Holborn. All rights reserved.
9
10pub mod adapter;
11pub mod catalog;
12pub mod delegation;
13pub mod descriptor;
14pub mod effects;
15pub mod error;
16pub mod gesture;
17pub mod id;
18pub mod request;
19pub mod target;
20pub mod qap_package;
21
22pub use adapter::AppAdapter;
23pub use catalog::CommandCatalog;
24pub use delegation::{
25    DelegationLifecycle, DelegationMode, ResourceBudgets, TaskDelegation,
26};
27pub use descriptor::{Availability, CommandDescriptor, TargetKind};
28pub use effects::{CommandEffect, EffectSet, InteractionKind, UndoPolicy};
29pub use error::ContractError;
30pub use gesture::{GestureCancel, GestureCommit, GestureSession, GestureUpdate};
31pub use id::{validate_finite_f64, AppId, CommandId, DecimalU64, JS_MAX_SAFE_INTEGER};
32pub use qap_package::*;
33pub use request::{
34    AppSessionDescriptor, CommandReceipt, CommandRequest, CommandStatus, JobDescriptor, JobState,
35    SurfaceDescriptor,
36};
37pub use target::{CommandTarget, InteractionContext, PointerHit, SelectionKind};
38
39/// Serialize a contract data structure to deterministic, pretty or compact JSON.
40pub fn to_json_string<T: serde::Serialize>(val: &T) -> Result<String, ContractError> {
41    serde_json::to_string(val).map_err(|e| ContractError::Serialization(e.to_string()))
42}
43
44/// Deserialize a contract data structure from JSON string.
45pub fn from_json_str<'a, T: serde::Deserialize<'a>>(s: &'a str) -> Result<T, ContractError> {
46    serde_json::from_str(s).map_err(|e| ContractError::Serialization(e.to_string()))
47}
48
49/// Serialize a contract data structure to canonical CBOR bytes.
50pub fn to_cbor_bytes<T: serde::Serialize>(val: &T) -> Result<Vec<u8>, ContractError> {
51    let mut buf = Vec::new();
52    ciborium::into_writer(val, &mut buf).map_err(|e| ContractError::Serialization(e.to_string()))?;
53    Ok(buf)
54}
55
56/// Deserialize a contract data structure from CBOR bytes.
57pub fn from_cbor_slice<T: serde::de::DeserializeOwned>(slice: &[u8]) -> Result<T, ContractError> {
58    ciborium::from_reader(slice).map_err(|e| ContractError::Serialization(e.to_string()))
59}