Skip to main content

qualia_core_db/governance/
tk_bc_labels.rs

1//! Traditional Knowledge (TK) & Biocultural (BC) Label Governance Policies (WP-4.5, Gap 14).
2//!
3//! Implements Local Contexts ENRICH / TK / BC label protocols into deontic policy matrices:
4//! - TK Attribution (`TK A`): Explicit cultural lineage and community attribution required.
5//! - TK Non-Commercial (`TK NC`): Commercial exploitation prohibited without consent agreement.
6//! - TK Culturally Sensitive (`TK CS`): Access restricted based on customary protocols.
7//! - BC Provenance (`BC P`): Biocultural lineage and ecological origin acknowledged.
8//! - TK Notice (`TK Open`): Open to collaboration and collective stewardship.
9//!
10//! Fail-closed: Violations yield an active `DeonticVerdict::Forbid`.
11
12use bytemuck::{Pod, Zeroable};
13use serde::{Deserialize, Serialize};
14
15/// Bitmask flags representing declared TK / BC labels on an asset or entity.
16#[repr(transparent)]
17#[derive(Debug, Clone, Copy, PartialEq, Eq, Pod, Zeroable, Serialize, Deserialize, Default)]
18pub struct TkBcLabelFlags(pub u32);
19
20impl TkBcLabelFlags {
21    pub const NONE: Self = Self(0);
22    /// TK Attribution: Community origin attribution required.
23    pub const TK_ATTRIBUTION: Self = Self(1 << 0);
24    /// TK Non-Commercial: Commercial extraction/monetization forbidden without consent.
25    pub const TK_NON_COMMERCIAL: Self = Self(1 << 1);
26    /// TK Culturally Sensitive: Seasonal or ritual sensitivity gating access.
27    pub const TK_CULTURALLY_SENSITIVE: Self = Self(1 << 2);
28    /// TK Verified: Community verification signed by verified custodians.
29    pub const TK_COMMUNITY_VERIFIED: Self = Self(1 << 3);
30    /// BC Provenance: Ecological/taxonomic origin in traditional lands.
31    pub const BC_PROVENANCE: Self = Self(1 << 4);
32    /// BC Multiple Community: Multi-custodian shared biological commons.
33    pub const BC_MULTIPLE_COMMUNITY: Self = Self(1 << 5);
34
35    /// `TkBcLabelFlags::has`.
36    pub const fn has(self, flag: Self) -> bool {
37        (self.0 & flag.0) != 0
38    }
39
40    /// `TkBcLabelFlags::union`.
41    pub const fn union(self, other: Self) -> Self {
42        Self(self.0 | other.0)
43    }
44}
45
46/// Evaluation context when accessing or deriving an asset bearing TK/BC labels.
47#[derive(Debug, Clone, PartialEq, Eq)]
48pub struct TkAccessContext {
49    pub is_commercial_use: bool,
50    pub has_attribution: bool,
51    pub community_consent_signed: bool,
52    pub observer_is_verified_custodian: bool,
53}
54
55/// Verdict returned by evaluating TK/BC governance policies.
56#[derive(Debug, Clone, Copy, PartialEq, Eq)]
57pub enum TkEvaluationVerdict {
58    /// Permitted: All cultural protocols and attribution requirements satisfied.
59    Permitted,
60    /// Prohibited: Commercial extraction without required consent agreement.
61    ProhibitedCommercialWithoutConsent,
62    /// Prohibited: Missing mandatory cultural attribution.
63    ProhibitedMissingAttribution,
64    /// Restricted: Culturally sensitive asset restricted to verified community members.
65    RestrictedCulturalSensitivity,
66}
67
68/// Evaluate an access or derivation request against declared TK/BC label flags.
69/// Operates in zero-heap time and fails closed on unverified conditions.
70pub fn evaluate_tk_bc_policy(
71    labels: TkBcLabelFlags,
72    context: &TkAccessContext,
73) -> TkEvaluationVerdict {
74    if labels.0 == 0 {
75        return TkEvaluationVerdict::Permitted;
76    }
77
78    // 1. Cultural Sensitivity check (highest precedence)
79    if labels.has(TkBcLabelFlags::TK_CULTURALLY_SENSITIVE)
80        && !context.observer_is_verified_custodian
81    {
82        return TkEvaluationVerdict::RestrictedCulturalSensitivity;
83    }
84
85    // 2. Commercial exploitation check
86    if labels.has(TkBcLabelFlags::TK_NON_COMMERCIAL)
87        && context.is_commercial_use
88        && !context.community_consent_signed
89    {
90        return TkEvaluationVerdict::ProhibitedCommercialWithoutConsent;
91    }
92
93    // 3. Attribution requirement check
94    if labels.has(TkBcLabelFlags::TK_ATTRIBUTION) && !context.has_attribution {
95        return TkEvaluationVerdict::ProhibitedMissingAttribution;
96    }
97
98    TkEvaluationVerdict::Permitted
99}
100
101#[cfg(test)]
102mod tests {
103    use super::*;
104
105    #[test]
106    fn test_tk_bc_policy_evaluation() {
107        let labels = TkBcLabelFlags::TK_ATTRIBUTION.union(TkBcLabelFlags::TK_NON_COMMERCIAL);
108
109        // Commercial use without consent fails
110        let commercial_ctx = TkAccessContext {
111            is_commercial_use: true,
112            has_attribution: true,
113            community_consent_signed: false,
114            observer_is_verified_custodian: false,
115        };
116        assert_eq!(
117            evaluate_tk_bc_policy(labels, &commercial_ctx),
118            TkEvaluationVerdict::ProhibitedCommercialWithoutConsent
119        );
120
121        // Commercial use WITH consent succeeds
122        let consent_ctx = TkAccessContext {
123            is_commercial_use: true,
124            has_attribution: true,
125            community_consent_signed: true,
126            observer_is_verified_custodian: false,
127        };
128        assert_eq!(
129            evaluate_tk_bc_policy(labels, &consent_ctx),
130            TkEvaluationVerdict::Permitted
131        );
132
133        // Non-commercial use without attribution fails
134        let no_attr_ctx = TkAccessContext {
135            is_commercial_use: false,
136            has_attribution: false,
137            community_consent_signed: false,
138            observer_is_verified_custodian: false,
139        };
140        assert_eq!(
141            evaluate_tk_bc_policy(labels, &no_attr_ctx),
142            TkEvaluationVerdict::ProhibitedMissingAttribution
143        );
144    }
145}