Skip to main content

qualia_app_contract/
adapter.rs

1//! Canonical AppAdapter trait defining the standardized engine boundary.
2
3use crate::descriptor::Availability;
4use crate::error::ContractError;
5use crate::gesture::{GestureCancel, GestureCommit, GestureSession, GestureUpdate};
6use crate::id::{CommandId, DecimalU64};
7use crate::request::{AppSessionDescriptor, CommandReceipt, CommandRequest, JobDescriptor};
8use crate::target::CommandTarget;
9
10/// Standardized adapter interface implemented by all application engines.
11///
12/// Ensures uniform hosting across browser Web Workers, native worker processes,
13/// and embedded shell stages.
14pub trait AppAdapter: Send + Sync {
15    /// Return the session and engine metadata descriptor.
16    fn describe(&self) -> Result<AppSessionDescriptor, ContractError>;
17
18    /// Open or create a document session in the specified mode ("read_only" or "read_write").
19    fn open(&mut self, _document_id: &str, _open_mode: &str) -> Result<DecimalU64, ContractError> {
20        Ok(DecimalU64(0))
21    }
22
23    /// Check command availability given the active target and selection.
24    fn availability(&self, _target: &CommandTarget, _command_id: &CommandId) -> Availability {
25        Availability::Available
26    }
27
28    /// Read-only inspection of the specified target object.
29    fn inspect(&self, _target: &CommandTarget) -> Result<serde_json::Value, ContractError> {
30        Ok(serde_json::Value::Null)
31    }
32
33    /// Execute an authorized command request and return the resulting receipt.
34    fn execute(&mut self, request: &CommandRequest) -> Result<CommandReceipt, ContractError>;
35
36    /// Begin an interactive gesture stream.
37    fn begin_gesture(&mut self, _session: &GestureSession) -> Result<(), ContractError> {
38        Err(ContractError::GesturesUnsupported("gestures unsupported".into()))
39    }
40
41    /// Stream incremental pointer updates to the active gesture.
42    fn update_gesture(&mut self, _update: &GestureUpdate) -> Result<(), ContractError> {
43        Err(ContractError::GesturesUnsupported("gestures unsupported".into()))
44    }
45
46    /// Commit an active gesture into an authoritative document revision.
47    fn commit_gesture(&mut self, _commit: &GestureCommit) -> Result<CommandReceipt, ContractError> {
48        Err(ContractError::GesturesUnsupported("gestures unsupported".into()))
49    }
50
51    /// Cancel an active gesture, discarding in-flight changes and restoring baseline revision.
52    fn cancel_gesture(&mut self, _cancel: &GestureCancel) -> Result<(), ContractError> {
53        Err(ContractError::GesturesUnsupported("gestures unsupported".into()))
54    }
55
56    /// Produce an opaque serialized snapshot of current document state.
57    fn snapshot(&self) -> Result<Vec<u8>, ContractError> {
58        Ok(Vec::new())
59    }
60
61    /// Restore document state from a serialized snapshot.
62    fn restore(&mut self, _snapshot_bytes: &[u8]) -> Result<(), ContractError> {
63        Ok(())
64    }
65
66    /// Poll status of a background or asynchronous job.
67    fn poll_job(&self, job_id: &str) -> Result<JobDescriptor, ContractError> {
68        Err(ContractError::InvalidIdentifier(format!("job {job_id} not found")))
69    }
70
71    /// Cancel a running background job.
72    fn cancel_job(&mut self, _job_id: &str) -> Result<(), ContractError> {
73        Ok(())
74    }
75
76    /// Close the active document session, releasing held memory and resources.
77    fn close(&mut self) -> Result<(), ContractError> {
78        Ok(())
79    }
80}