Skip to main content

qualia_app_contract/
request.rs

1//! Command requests, receipts, session descriptors, surfaces, and job DTOs.
2
3use crate::effects::EffectSet;
4use crate::id::{AppId, CommandId, DecimalU64};
5use crate::target::CommandTarget;
6use serde::{Deserialize, Serialize};
7
8/// Execution status reported in a CommandReceipt.
9#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
10#[serde(rename_all = "snake_case")]
11pub enum CommandStatus {
12    Success,
13    Failure,
14    Pending,
15    Cancelled,
16}
17
18/// Normalized command execution request.
19#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
20pub struct CommandRequest {
21    pub request_id: String,
22    pub command_id: CommandId,
23    pub command_version: String,
24    pub target: CommandTarget,
25    pub params: serde_json::Value,
26    pub expected_revision: DecimalU64,
27    pub actor_id: String,
28    #[serde(skip_serializing_if = "Option::is_none")]
29    pub delegation_id: Option<String>,
30    #[serde(skip_serializing_if = "Option::is_none")]
31    pub approval_id: Option<String>,
32    pub idempotency_key: String,
33}
34
35/// Cryptographically verifiable or auditable command execution receipt.
36#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
37pub struct CommandReceipt {
38    pub request_id: String,
39    pub actor_id: String,
40    pub app_id: AppId,
41    pub command_id: CommandId,
42    pub target_id: String,
43    pub before_revision: DecimalU64,
44    pub after_revision: DecimalU64,
45    pub status: CommandStatus,
46    pub effects: EffectSet,
47    pub result: serde_json::Value,
48    #[serde(skip_serializing_if = "Option::is_none")]
49    pub job_handle: Option<String>,
50    #[serde(default, skip_serializing_if = "Vec::is_empty")]
51    pub warnings: Vec<String>,
52    #[serde(skip_serializing_if = "Option::is_none")]
53    pub provenance_ref: Option<String>,
54    #[serde(skip_serializing_if = "Option::is_none")]
55    pub authority_decision_ref: Option<String>,
56    #[serde(skip_serializing_if = "Option::is_none")]
57    pub cost_cents: Option<DecimalU64>,
58}
59
60/// Metadata descriptor for an active application session.
61#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
62pub struct AppSessionDescriptor {
63    pub app_version: String,
64    pub package_digest: String,
65    pub engine_version: String,
66    pub schema_version: u32,
67    pub session_id: String,
68    pub document_id: String,
69    pub open_mode: String,
70    pub revision: DecimalU64,
71    pub is_dirty: bool,
72    pub is_durable: bool,
73    pub execution_source: String,
74    #[serde(default, skip_serializing_if = "Vec::is_empty")]
75    pub capabilities: Vec<String>,
76    #[serde(default, skip_serializing_if = "Vec::is_empty")]
77    pub payload_refs: Vec<String>,
78}
79
80/// Descriptor for a presentation or interactive surface.
81#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
82pub struct SurfaceDescriptor {
83    pub surface_id: String,
84    pub surface_version: String,
85    pub kind: String,
86    pub document_binding: String,
87    pub view_type: String,
88    #[serde(default, skip_serializing_if = "Vec::is_empty")]
89    pub required_capabilities: Vec<String>,
90    #[serde(default, skip_serializing_if = "Vec::is_empty")]
91    pub input_kinds: Vec<String>,
92    pub accessibility_projection: String,
93    pub state_schema: String,
94    pub resource_budget_class: String,
95}
96
97/// Lifecycle state of an asynchronous domain job.
98#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
99#[serde(rename_all = "snake_case")]
100pub enum JobState {
101    Queued,
102    Running,
103    Succeeded,
104    Failed,
105    Cancelled,
106}
107
108/// Descriptor for tracking background or long-running tasks.
109#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
110pub struct JobDescriptor {
111    pub job_id: String,
112    pub request_id: String,
113    pub actor_id: String,
114    pub target_id: String,
115    pub state: JobState,
116    #[serde(skip_serializing_if = "Option::is_none")]
117    pub completed_units: Option<u64>,
118    #[serde(skip_serializing_if = "Option::is_none")]
119    pub total_units: Option<u64>,
120    pub cancellable: bool,
121    pub external_effect_state: String,
122    #[serde(default, skip_serializing_if = "Vec::is_empty")]
123    pub diagnostics: Vec<String>,
124    #[serde(skip_serializing_if = "Option::is_none")]
125    pub result_ref: Option<String>,
126    #[serde(skip_serializing_if = "Option::is_none")]
127    pub provenance_ref: Option<String>,
128}