Skip to main content

qualia_cooperative_core/
agency_domain.rs

1//! `AgencyDomain` — the ~17 **domains of agency** a principal may delegate under a supported-agency
2//! relationship (see `docs/plans/adr-authority-attestation-guardianship-model.md` §7).
3//!
4//! (Timothy, 2026-07-03; grounded in the "Agency / Social Book" source and the ADR REFRAME.)
5//! This is the *what* of a delegation: which slice of a person's socio-legal life an agent is
6//! trusted to help with — an accountant in the **financial** domain, a clinical psychologist in
7//! **medical/personal-welfare**, an IT social worker in **it-social-work**, a bot standing in as a
8//! declared source of truth for someone isolated in **communication** or **social-welfare**.
9//!
10//! Two invariants from the source works are load-bearing here:
11//! - **Personhood is what gets delegated, never selfhood.** Sixteen of the seventeen domains are
12//!   *personhood* (the socio-legal relationship, delegable under an appropriate role). The lone
13//!   exception — **reproductive / biometric / genetic** — touches *selfhood*, inherent to the person:
14//!   it is the highest bar, never casually delegated, and carried here only so the model can name it
15//!   and refuse to treat it like the others. (See `taxonomy::Sphere`.)
16//! - **Consequentiality is explicit.** A handful of domains (medical, legal, financial,
17//!   reproductive/biometric/genetic, civic-political) carry a `consequential` marker so higher
18//!   attestation/threshold requirements can key off it rather than off ad-hoc rules.
19//!
20//! Modelled as open data in a [`Taxonomy`] so jurisdiction packs, hybrids, and "domain fabrics" can
21//! extend the vocabulary without a code change. The seventeen well-known domains and their four
22//! grouping categories (welfare, socio-economic, technological, civic) get `const` ids.
23
24use crate::taxonomy::{Taxonomy, TaxonomyTerm};
25
26/// Stable ids for the seeded categories and the seventeen domains (open registry — well-known ones).
27pub mod ids {
28    // Categories (coarse groupings of domains).
29    pub const CATEGORY_WELFARE: &str = "urn:qualia:agency-domain:category:welfare";
30    pub const CATEGORY_SOCIO_ECONOMIC: &str = "urn:qualia:agency-domain:category:socio_economic";
31    pub const CATEGORY_TECHNOLOGICAL: &str = "urn:qualia:agency-domain:category:technological";
32    pub const CATEGORY_CIVIC: &str = "urn:qualia:agency-domain:category:civic";
33
34    // Welfare domains.
35    pub const MEDICAL: &str = "urn:qualia:agency-domain:welfare:medical";
36    pub const PERSONAL_WELFARE: &str = "urn:qualia:agency-domain:welfare:personal_welfare";
37    pub const RESIDENTIAL: &str = "urn:qualia:agency-domain:welfare:residential";
38    pub const SUPERVISORY_PROTECTIVE: &str =
39        "urn:qualia:agency-domain:welfare:supervisory_protective";
40    pub const REPRODUCTIVE_BIOMETRIC_GENETIC: &str =
41        "urn:qualia:agency-domain:welfare:reproductive_biometric_genetic";
42
43    // Socio-economic domains.
44    pub const FINANCIAL: &str = "urn:qualia:agency-domain:socio_economic:financial";
45    pub const LEGAL: &str = "urn:qualia:agency-domain:socio_economic:legal";
46    pub const EDUCATION_TRAINING: &str =
47        "urn:qualia:agency-domain:socio_economic:education_training";
48    pub const SOCIAL_WELFARE: &str = "urn:qualia:agency-domain:socio_economic:social_welfare";
49
50    // Technological domains.
51    pub const IT_SOCIAL_WORK: &str = "urn:qualia:agency-domain:technological:it_social_work";
52    pub const DIGITAL_IDENTITY: &str = "urn:qualia:agency-domain:technological:digital_identity";
53    pub const DATA_PRIVACY_CONSENT: &str =
54        "urn:qualia:agency-domain:technological:data_privacy_consent";
55    pub const COMMUNICATION: &str = "urn:qualia:agency-domain:technological:communication";
56    pub const REPUTATIONAL: &str = "urn:qualia:agency-domain:technological:reputational";
57    pub const DIGITAL_LEGACY: &str = "urn:qualia:agency-domain:technological:digital_legacy";
58    pub const AI_PROXY: &str = "urn:qualia:agency-domain:technological:ai_proxy";
59
60    // Civic domains.
61    pub const CIVIC_POLITICAL: &str = "urn:qualia:agency-domain:civic:civic_political";
62}
63
64/// Attribute key: the sphere a domain touches (`"personhood"` for all but reproductive/biometric/genetic).
65const ATTR_SPHERE: &str = "sphere";
66/// Attribute key: `"true"` when the domain is high-stakes and needs a higher attestation bar.
67const ATTR_CONSEQUENTIAL: &str = "consequential";
68/// Attribute key: a short comma list of the data classes a delegation in this domain touches.
69const ATTR_DATA_CLASSES: &str = "data_classes";
70
71/// Build one domain term: grouped under its category, described, and tagged with sphere / consequential /
72/// data-class attributes so ABAC axioms and threshold rules can read them without magic strings.
73fn domain(
74    id: &str,
75    label: &str,
76    category: &str,
77    description: &str,
78    selfhood: bool,
79    consequential: bool,
80    data_classes: &str,
81) -> TaxonomyTerm {
82    TaxonomyTerm::new(id, label)
83        .in_category(category)
84        .described(description)
85        .with_attr(
86            ATTR_SPHERE,
87            if selfhood { "selfhood" } else { "personhood" },
88        )
89        .with_attr(
90            ATTR_CONSEQUENTIAL,
91            if consequential { "true" } else { "false" },
92        )
93        .with_attr(ATTR_DATA_CLASSES, data_classes)
94}
95
96/// Build a coarse category term (a grouping of domains).
97fn category(id: &str, label: &str) -> TaxonomyTerm {
98    TaxonomyTerm::new(id, label).with_attr("kind", "category")
99}
100
101/// The seeded domains-of-agency taxonomy: four category terms plus the seventeen domains.
102/// Extend with `insert` / `extend_with` for jurisdiction packs, hybrids, or domain fabrics.
103pub fn agency_domain_taxonomy() -> Taxonomy {
104    use ids::*;
105    Taxonomy::from_terms([
106        // Categories.
107        category(CATEGORY_WELFARE, "Welfare"),
108        category(CATEGORY_SOCIO_ECONOMIC, "Socio-economic"),
109        category(CATEGORY_TECHNOLOGICAL, "Technological"),
110        category(CATEGORY_CIVIC, "Civic"),
111        // Welfare domains.
112        domain(
113            MEDICAL,
114            "Medical (healthcare proxy)",
115            CATEGORY_WELFARE,
116            "Consenting to, coordinating, or refusing medical treatment on the principal's behalf as a healthcare proxy, within their known wishes.",
117            false,
118            true,
119            "diagnosis,medication,treatment",
120        ),
121        domain(
122            PERSONAL_WELFARE,
123            "Personal welfare",
124            CATEGORY_WELFARE,
125            "Day-to-day wellbeing decisions — diet, routine, personal care, social contact — that support the principal without overriding their preferences.",
126            false,
127            false,
128            "care_needs,daily_routine,preferences",
129        ),
130        domain(
131            RESIDENTIAL,
132            "Residential",
133            CATEGORY_WELFARE,
134            "Where and how the principal lives — housing, tenancy, and living arrangements — arranged in line with their choices.",
135            false,
136            false,
137            "address,tenancy,accommodation",
138        ),
139        domain(
140            SUPERVISORY_PROTECTIVE,
141            "Supervisory / protective",
142            CATEGORY_WELFARE,
143            "Oversight to prevent abuse, neglect, or exploitation, with an evidence chain — protective, not custodial capture of the person.",
144            false,
145            false,
146            "safeguarding_alerts,incident_reports",
147        ),
148        domain(
149            REPRODUCTIVE_BIOMETRIC_GENETIC,
150            "Reproductive / biometric / genetic",
151            CATEGORY_WELFARE,
152            "Reproductive autonomy, biometric templates, and genomic data — inherent to the self; the highest bar, never casually delegated.",
153            true, // selfhood, not personhood.
154            true,
155            "genome,biometrics,reproductive_autonomy",
156        ),
157        // Socio-economic domains.
158        domain(
159            FINANCIAL,
160            "Financial",
161            CATEGORY_SOCIO_ECONOMIC,
162            "Managing money, accounts, assets, and transactions on the principal's behalf — the accountant / fiduciary case.",
163            false,
164            true,
165            "accounts,transactions,assets,tax",
166        ),
167        domain(
168            LEGAL,
169            "Legal",
170            CATEGORY_SOCIO_ECONOMIC,
171            "Acting in legal matters — representation, contracts, filings, and rights enforcement — under the principal's instruction.",
172            false,
173            true,
174            "contracts,filings,representation",
175        ),
176        domain(
177            EDUCATION_TRAINING,
178            "Education & training",
179            CATEGORY_SOCIO_ECONOMIC,
180            "Enrolment, learning pathways, credentials, and skill development the principal is pursuing or has authorised.",
181            false,
182            false,
183            "enrolment,credentials,progress",
184        ),
185        domain(
186            SOCIAL_WELFARE,
187            "Social welfare",
188            CATEGORY_SOCIO_ECONOMIC,
189            "Benefits, entitlements, and social-support services — applying for and coordinating the safety-net a principal is entitled to.",
190            false,
191            false,
192            "benefits,entitlements,claims",
193        ),
194        // Technological domains.
195        domain(
196            IT_SOCIAL_WORK,
197            "IT social work",
198            CATEGORY_TECHNOLOGICAL,
199            "Hands-on help with devices, accounts, and online services for a principal who needs technical support to exercise agency.",
200            false,
201            false,
202            "devices,accounts,support_tickets",
203        ),
204        domain(
205            DIGITAL_IDENTITY,
206            "Digital identity",
207            CATEGORY_TECHNOLOGICAL,
208            "Managing the principal's credentials, DIDs, and identity assertions — who they are online — without impersonating them.",
209            false,
210            false,
211            "dids,credentials,identity_assertions",
212        ),
213        domain(
214            DATA_PRIVACY_CONSENT,
215            "Data privacy & consent",
216            CATEGORY_TECHNOLOGICAL,
217            "Granting, scoping, and revoking consent to share the principal's data — the gatekeeping of who may see what.",
218            false,
219            false,
220            "consent_grants,data_shares,revocations",
221        ),
222        domain(
223            COMMUNICATION,
224            "Communication",
225            CATEGORY_TECHNOLOGICAL,
226            "Sending, receiving, and triaging messages on the principal's behalf — a declared source of truth when they are isolated or overwhelmed.",
227            false,
228            false,
229            "messages,contacts,correspondence",
230        ),
231        domain(
232            REPUTATIONAL,
233            "Reputational",
234            CATEGORY_TECHNOLOGICAL,
235            "Stewarding the principal's public presence and standing — profiles, reviews, and how they are represented to others.",
236            false,
237            false,
238            "profiles,reviews,public_statements",
239        ),
240        domain(
241            DIGITAL_LEGACY,
242            "Digital legacy",
243            CATEGORY_TECHNOLOGICAL,
244            "Handling accounts, data, and assets after death or long-term incapacity — the digital-will / executor case.",
245            false,
246            false,
247            "account_closures,data_bequests,memorialisation",
248        ),
249        domain(
250            AI_PROXY,
251            "AI proxy",
252            CATEGORY_TECHNOLOGICAL,
253            "A software agent executing the principal's pre-declared intents or monitoring streams on their behalf, without overriding their ultimate authority.",
254            false,
255            false,
256            "declared_intents,monitoring_streams,agent_actions",
257        ),
258        // Civic domains.
259        domain(
260            CIVIC_POLITICAL,
261            "Civic / political",
262            CATEGORY_CIVIC,
263            "Exercising civic and political agency — voting information, petitions, representations to authorities — amplifying the principal's own voice.",
264            false,
265            true,
266            "voting_info,petitions,representations",
267        ),
268    ])
269}
270
271/// Whether a domain is flagged high-stakes (`consequential = "true"`), needing a higher attestation
272/// bar. Reads the seeded attribute; an unknown id (or one lacking the attribute) is `false`.
273pub fn is_consequential(tax: &Taxonomy, domain_id: &str) -> bool {
274    tax.get(domain_id).and_then(|t| t.attr(ATTR_CONSEQUENTIAL)) == Some("true")
275}
276
277#[cfg(test)]
278mod tests {
279    use super::ids::*;
280    use super::*;
281    use crate::taxonomy::Sphere;
282
283    /// Every seeded domain id, for exhaustive coverage checks.
284    const ALL_DOMAINS: [&str; 17] = [
285        MEDICAL,
286        PERSONAL_WELFARE,
287        RESIDENTIAL,
288        SUPERVISORY_PROTECTIVE,
289        REPRODUCTIVE_BIOMETRIC_GENETIC,
290        FINANCIAL,
291        LEGAL,
292        EDUCATION_TRAINING,
293        SOCIAL_WELFARE,
294        IT_SOCIAL_WORK,
295        DIGITAL_IDENTITY,
296        DATA_PRIVACY_CONSENT,
297        COMMUNICATION,
298        REPUTATIONAL,
299        DIGITAL_LEGACY,
300        AI_PROXY,
301        CIVIC_POLITICAL,
302    ];
303
304    #[test]
305    fn exactly_seventeen_domains_across_four_categories() {
306        let tax = agency_domain_taxonomy();
307        let welfare = tax.in_category(CATEGORY_WELFARE).len();
308        let socio = tax.in_category(CATEGORY_SOCIO_ECONOMIC).len();
309        let tech = tax.in_category(CATEGORY_TECHNOLOGICAL).len();
310        let civic = tax.in_category(CATEGORY_CIVIC).len();
311        assert_eq!(welfare, 5, "welfare should hold 5 domains");
312        assert_eq!(socio, 4, "socio-economic should hold 4 domains");
313        assert_eq!(tech, 7, "technological should hold 7 domains");
314        assert_eq!(civic, 1, "civic should hold 1 domain");
315        assert_eq!(welfare + socio + tech + civic, 17, "17 domains total");
316        // Four categories + seventeen domains = twenty-one terms.
317        assert_eq!(tax.len(), 21);
318    }
319
320    #[test]
321    fn every_named_domain_id_is_present_and_categorised() {
322        let tax = agency_domain_taxonomy();
323        for id in ALL_DOMAINS {
324            let term = tax
325                .get(id)
326                .unwrap_or_else(|| panic!("missing domain: {id}"));
327            assert!(
328                term.category.is_some(),
329                "domain {id} must sit in a category"
330            );
331            assert!(
332                !term.description.is_empty(),
333                "domain {id} must have a description"
334            );
335            // Every domain names at least one data class.
336            assert!(
337                !term.attr_list(ATTR_DATA_CLASSES).is_empty(),
338                "domain {id} must list data classes"
339            );
340        }
341    }
342
343    #[test]
344    fn exactly_five_consequential_domains_and_they_are_the_right_ones() {
345        let tax = agency_domain_taxonomy();
346        let expected_consequential = [
347            MEDICAL,
348            LEGAL,
349            FINANCIAL,
350            REPRODUCTIVE_BIOMETRIC_GENETIC,
351            CIVIC_POLITICAL,
352        ];
353        let consequential: Vec<&str> = ALL_DOMAINS
354            .iter()
355            .copied()
356            .filter(|id| is_consequential(&tax, id))
357            .collect();
358        assert_eq!(
359            consequential.len(),
360            5,
361            "exactly five domains are consequential, got {consequential:?}"
362        );
363        for id in expected_consequential {
364            assert!(is_consequential(&tax, id), "{id} should be consequential");
365        }
366        // And nothing else is.
367        for id in ALL_DOMAINS {
368            let should = expected_consequential.contains(&id);
369            assert_eq!(
370                is_consequential(&tax, id),
371                should,
372                "consequential flag wrong for {id}"
373            );
374        }
375    }
376
377    #[test]
378    fn reproductive_biometric_genetic_is_selfhood_and_all_others_are_personhood() {
379        let tax = agency_domain_taxonomy();
380        for id in ALL_DOMAINS {
381            let term = tax.get(id).unwrap();
382            if id == REPRODUCTIVE_BIOMETRIC_GENETIC {
383                assert_eq!(
384                    term.sphere(),
385                    Sphere::Selfhood,
386                    "reproductive/biometric/genetic touches selfhood"
387                );
388            } else {
389                assert_eq!(
390                    term.sphere(),
391                    Sphere::Personhood,
392                    "{id} should be a personhood domain"
393                );
394            }
395        }
396    }
397
398    #[test]
399    fn is_consequential_reads_the_attribute() {
400        let tax = agency_domain_taxonomy();
401        assert!(is_consequential(&tax, MEDICAL));
402        assert!(!is_consequential(&tax, COMMUNICATION));
403    }
404
405    #[test]
406    fn is_consequential_is_false_for_unknown_id() {
407        let tax = agency_domain_taxonomy();
408        assert!(!is_consequential(
409            &tax,
410            "urn:qualia:agency-domain:welfare:does-not-exist"
411        ));
412        assert!(!is_consequential(&tax, ""));
413    }
414
415    #[test]
416    fn category_terms_are_not_counted_as_domains() {
417        let tax = agency_domain_taxonomy();
418        // A category term carries no consequential attribute → is_consequential is false,
419        // and it is not a member of any category itself (top-level).
420        assert!(!is_consequential(&tax, CATEGORY_WELFARE));
421        assert!(tax.get(CATEGORY_WELFARE).unwrap().category.is_none());
422        assert_eq!(
423            tax.get(CATEGORY_WELFARE).unwrap().attr("kind"),
424            Some("category")
425        );
426    }
427
428    #[test]
429    fn medical_data_classes_parse() {
430        let tax = agency_domain_taxonomy();
431        let classes = tax.get(MEDICAL).unwrap().attr_list(ATTR_DATA_CLASSES);
432        assert_eq!(classes, vec!["diagnosis", "medication", "treatment"]);
433    }
434
435    #[test]
436    fn taxonomy_round_trips_through_json() {
437        let tax = agency_domain_taxonomy();
438        let json = serde_json::to_string(&tax).unwrap();
439        let back: Taxonomy = serde_json::from_str(&json).unwrap();
440        assert_eq!(tax, back);
441        assert!(back.contains(AI_PROXY));
442    }
443}