Skip to main content

qualia_app_contract/
qap_package.rs

1//! Portable, Multi-Repo Qap Package & Host Lifecycle Contract.
2//!
3//! Defines the multi-repo distribution, repository source, and shared-service
4//! dependency model enabling independent Git repository development, versioning,
5//! installation, updates, and rollbacks.
6//! Follows AGENTS.md ยง0-B (< 260 lines).
7
8use serde::{Deserialize, Serialize};
9use std::collections::BTreeMap;
10
11/// Distribution mode for a Qap application.
12#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
13pub enum QapDistributionMode {
14    BundledCore,
15    SeparateRepoDownloadable,
16    LocalDevTree,
17}
18
19/// Shared OS-Shell system service dependency.
20#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
21pub enum QapSharedServiceDep {
22    Scheduler,
23    Networking,
24    PermissiveCommons,
25    CommunicationsBus,
26    IdentifiersAndConsequence,
27}
28
29/// Upstream repository and signing provenance for a Qap.
30#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
31pub struct QapRepoSource {
32    pub repo_url: String,
33    pub did_git: String,
34    pub release_channel: String,
35    pub signer_identifier_did: String,
36}
37
38/// Complete multi-repo specification for an installable/updatable Qap.
39#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
40pub struct QapPackageSpec {
41    pub qap_id: String,
42    pub display_name: String,
43    pub version: String,
44    pub abi_version: String,
45    pub distribution: QapDistributionMode,
46    pub repo: QapRepoSource,
47    pub shared_services: Vec<QapSharedServiceDep>,
48    pub required_ontologies: Vec<String>,
49    pub entrypoints: BTreeMap<String, String>,
50}
51
52impl QapPackageSpec {
53    pub fn new(
54        qap_id: &str,
55        display_name: &str,
56        version: &str,
57        abi_version: &str,
58        distribution: QapDistributionMode,
59        repo_url: &str,
60        did_git: &str,
61        release_channel: &str,
62        signer_identifier_did: &str,
63        shared_services: Vec<QapSharedServiceDep>,
64        required_ontologies: Vec<&str>,
65        entrypoint_rel: &str,
66    ) -> Self {
67        let mut entrypoints = BTreeMap::new();
68        entrypoints.insert("main".into(), entrypoint_rel.into());
69        Self {
70            qap_id: qap_id.into(),
71            display_name: display_name.into(),
72            version: version.into(),
73            abi_version: abi_version.into(),
74            distribution,
75            repo: QapRepoSource {
76                repo_url: repo_url.into(),
77                did_git: did_git.into(),
78                release_channel: release_channel.into(),
79                signer_identifier_did: signer_identifier_did.into(),
80            },
81            shared_services,
82            required_ontologies: required_ontologies.into_iter().map(String::from).collect(),
83            entrypoints,
84        }
85    }
86}
87
88/// Returns the 7 canonical core Qap specifications with separate multi-repo sources.
89pub fn canonical_core_qaps() -> Vec<QapPackageSpec> {
90    use QapDistributionMode::*;
91    use QapSharedServiceDep::*;
92    let signer = "did:q42:release-signer";
93    vec![
94        QapPackageSpec::new(
95            "poet",
96            "POET Core HyperCanvas & Spatial Studio",
97            "1.0.0",
98            "1.0",
99            BundledCore,
100            "https://github.com/webizen/qap-poet",
101            "did:git:webizen:qap-poet",
102            "stable",
103            signer,
104            vec![Scheduler, Networking, PermissiveCommons, IdentifiersAndConsequence],
105            vec!["qualia:PoetCore", "qualia:HyperCanvas"],
106            "index.html#studio",
107        ),
108        QapPackageSpec::new(
109            "wallet-crypto",
110            "Multi-Chain Sovereign Wallet & Economic Settlement",
111            "1.0.0",
112            "1.0",
113            BundledCore,
114            "https://github.com/webizen/qap-wallet",
115            "did:git:webizen:qap-wallet",
116            "stable",
117            signer,
118            vec![IdentifiersAndConsequence, PermissiveCommons, Networking],
119            vec!["qualia:Econ", "qualia:MultiChain"],
120            "index.html#wallet",
121        ),
122        QapPackageSpec::new(
123            "cooperative-projects",
124            "Cooperative Projects & Labor Accounting Commons",
125            "1.0.0",
126            "1.0",
127            BundledCore,
128            "https://github.com/webizen/qap-coop",
129            "did:git:webizen:qap-coop",
130            "stable",
131            signer,
132            vec![Scheduler, CommunicationsBus, PermissiveCommons],
133            vec!["qualia:CooperativeWork", "qualia:Labor"],
134            "index.html#coop",
135        ),
136        QapPackageSpec::new(
137            "hypermedia-library",
138            "Hypermedia Asset & Aspect Graph Library",
139            "1.0.0",
140            "1.0",
141            BundledCore,
142            "https://github.com/webizen/qap-hypermedia",
143            "did:git:webizen:qap-hypermedia",
144            "stable",
145            signer,
146            vec![Networking, Scheduler, PermissiveCommons],
147            vec!["qualia:Hypermedia", "qualia:AspectGraph"],
148            "index.html#library",
149        ),
150        QapPackageSpec::new(
151            "llm-agents",
152            "Local LLM Swarm & Agentic Choreography",
153            "1.0.0",
154            "1.0",
155            SeparateRepoDownloadable,
156            "https://github.com/webizen/qap-llm-agents",
157            "did:git:webizen:qap-llm-agents",
158            "beta",
159            signer,
160            vec![Scheduler, PermissiveCommons, CommunicationsBus],
161            vec!["qualia:Agentic", "qualia:LLM"],
162            "index.html#agents",
163        ),
164        QapPackageSpec::new(
165            "communications-directory",
166            "Consent-Gated Purpose Messaging & DID Directory",
167            "1.0.0",
168            "1.0",
169            BundledCore,
170            "https://github.com/webizen/qap-comms",
171            "did:git:webizen:qap-comms",
172            "stable",
173            signer,
174            vec![CommunicationsBus, IdentifiersAndConsequence, Networking],
175            vec!["qualia:Communications", "qualia:Directory"],
176            "index.html#directory",
177        ),
178        QapPackageSpec::new(
179            "web-browser",
180            "Webizen Spatial Browser & Solid LDP Client",
181            "1.0.0",
182            "1.0",
183            SeparateRepoDownloadable,
184            "https://github.com/webizen/qap-browser",
185            "did:git:webizen:qap-browser",
186            "beta",
187            signer,
188            vec![Networking, PermissiveCommons, IdentifiersAndConsequence],
189            vec!["qualia:Webizen", "qualia:SolidLDP"],
190            "index.html#browser",
191        ),
192    ]
193}
194
195#[cfg(test)]
196mod tests {
197    use super::*;
198    use std::collections::BTreeSet;
199
200    #[test]
201    fn test_canonical_core_qaps_validation() {
202        let qaps = canonical_core_qaps();
203        assert_eq!(qaps.len(), 7);
204
205        let mut did_gits = BTreeSet::new();
206        let mut repo_urls = BTreeSet::new();
207
208        for qap in &qaps {
209            assert!(!qap.qap_id.is_empty());
210            assert!(!qap.display_name.is_empty());
211            assert_eq!(qap.version, "1.0.0");
212            assert_eq!(qap.abi_version, "1.0");
213            assert!(qap.repo.repo_url.starts_with("https://github.com/webizen/qap-"));
214            assert!(qap.repo.did_git.starts_with("did:git:webizen:qap-"));
215            assert_eq!(qap.repo.signer_identifier_did, "did:q42:release-signer");
216            assert!(!qap.shared_services.is_empty());
217            assert!(!qap.entrypoints.is_empty());
218
219            assert!(did_gits.insert(qap.repo.did_git.clone()), "duplicate did_git: {}", qap.repo.did_git);
220            assert!(repo_urls.insert(qap.repo.repo_url.clone()), "duplicate repo_url: {}", qap.repo.repo_url);
221        }
222
223        assert_eq!(did_gits.len(), 7);
224        assert_eq!(repo_urls.len(), 7);
225    }
226}