Skip to main content

qualia_client_core/wellfair/api/
welfare_work.rs

1//! Welfare support + cooperative work items
2
3use super::super::blob_store::BlobStore;
4use super::super::journal::JournalEntry;
5use qualia_cooperative_core::work_item::{
6    build_work_item_envelope, build_work_item_status_envelope, derive_board,
7    parse_work_item_status_summary, parse_work_item_summary, work_item_status_summary,
8    work_item_summary, BoardColumn, WorkItem, WorkItemStatusEvent,
9};
10use wellfare_core::authority_attestation::{
11    authority_attestation_summary, build_authority_attestation_envelope, AgentInCapacity,
12    Authority, AuthorityAttestation, Representation,
13};
14use wellfare_core::welfare_support::{
15    build_assistance_need_envelope, build_government_letter_envelope,
16    build_welfare_stream_envelope, AssistanceNeed, GovernmentLetter, StreamStatus, Urgency,
17    WelfareStream,
18};
19
20use super::*;
21
22impl WebizenHostApi {
23    // --- Welfare support (Phase 3 / LIF-08..) ---
24
25    /// Adds assistance-need.
26    pub fn add_assistance_need(
27        &mut self,
28        category: &str,
29        description: &str,
30        urgency: Urgency,
31    ) -> Result<JournalEntry, String> {
32        let mut need = AssistanceNeed::new(category, description, Self::now_unix() as u32);
33        need.urgency = urgency;
34        let hash =
35            Self::payload_hash_hex(&serde_json::to_string(&need).map_err(|e| e.to_string())?);
36        let asserted = Self::now_unix() as u32;
37        let envelope = build_assistance_need_envelope(
38            &need,
39            &self.owner_did,
40            &self.author_did,
41            asserted,
42            Some(hash),
43        );
44        let summary = wellfare_core::welfare_support::assistance_need_summary(&need);
45        self.submit_record_with_summary(QAPP_WELFARE, envelope, SOURCE_WELFARE, Some(summary))?;
46        self.finalize_batch().ok();
47        self.latest_journal_entry()
48    }
49
50    /// Adds welfare-stream.
51    pub fn add_welfare_stream(
52        &mut self,
53        program_name: &str,
54        reference: Option<String>,
55        status: StreamStatus,
56    ) -> Result<JournalEntry, String> {
57        let mut stream = WelfareStream::new(program_name, Self::now_unix() as u32);
58        stream.reference = reference.filter(|s| !s.is_empty());
59        stream.status = status;
60        let hash =
61            Self::payload_hash_hex(&serde_json::to_string(&stream).map_err(|e| e.to_string())?);
62        let asserted = Self::now_unix() as u32;
63        let envelope = build_welfare_stream_envelope(
64            &stream,
65            &self.owner_did,
66            &self.author_did,
67            asserted,
68            Some(hash),
69        );
70        let summary = wellfare_core::welfare_support::welfare_stream_summary(&stream);
71        self.submit_record_with_summary(QAPP_WELFARE, envelope, SOURCE_WELFARE, Some(summary))?;
72        self.finalize_batch().ok();
73        self.latest_journal_entry()
74    }
75
76    /// Adds government-letter.
77    pub fn add_government_letter(
78        &mut self,
79        sender: &str,
80        subject: &str,
81        action_required: bool,
82    ) -> Result<JournalEntry, String> {
83        let mut letter = GovernmentLetter::new(sender, subject, Self::now_unix() as u32);
84        letter.action_required = action_required;
85        let asserted = Self::now_unix() as u32;
86        let envelope =
87            build_government_letter_envelope(&letter, &self.owner_did, &self.author_did, asserted);
88        let summary = wellfare_core::welfare_support::government_letter_summary(&letter);
89        self.submit_record_with_summary(QAPP_WELFARE, envelope, SOURCE_WELFARE, Some(summary))?;
90        self.finalize_batch().ok();
91        self.latest_journal_entry()
92    }
93
94    /// Record a general **authority attestation** — the ontological generalization of a government
95    /// letter: an authorizing body (extensible type + jurisdiction + department) attested by an
96    /// agent-in-capacity, delivered as a PDF, a credential, or a PDF-with-embedded-credential.
97    /// `add_government_letter` remains a preset (`authority:government`, PDF) of this model.
98    #[allow(clippy::too_many_arguments)]
99    pub fn add_authority_attestation(
100        &mut self,
101        authority_type: &str,
102        authority_label: &str,
103        jurisdiction: Option<String>,
104        department: Option<String>,
105        agent_name: Option<String>,
106        agent_capacity: Option<String>,
107        representation: &str,
108        subject: &str,
109        statement: &str,
110        action_required: bool,
111    ) -> Result<JournalEntry, String> {
112        let issued = Self::now_unix() as u32;
113        let authority = Authority::new(authority_type, authority_label);
114        let representation = match representation.to_ascii_lowercase().as_str() {
115            "credential" => Representation::Credential,
116            "pdf_with_embedded_credential" | "both" => Representation::PdfWithEmbeddedCredential,
117            _ => Representation::Pdf,
118        };
119        let mut att = AuthorityAttestation::new(authority, subject, statement, issued)
120            .with_representation(representation)
121            .with_action_required(action_required);
122        if let Some(j) = jurisdiction {
123            att = att.with_jurisdiction(j);
124        }
125        if let Some(d) = department {
126            att = att.with_department(d);
127        }
128        if let (Some(n), Some(c)) = (agent_name, agent_capacity) {
129            att = att.with_agent(AgentInCapacity::new(n, c));
130        }
131        let envelope =
132            build_authority_attestation_envelope(&att, &self.owner_did, &self.author_did, issued);
133        let summary = authority_attestation_summary(&att);
134        self.submit_record_with_summary(QAPP_WELFARE, envelope, SOURCE_WELFARE, Some(summary))?;
135        self.finalize_batch().ok();
136        self.latest_journal_entry()
137    }
138
139    /// Record a government letter together with its document bytes (stored as a content-addressed
140    /// blob; the letter's `attachment_blob_hash` is that blob's hash, retrievable via `attachment_bytes`).
141    pub fn add_government_letter_attachment(
142        &mut self,
143        sender: &str,
144        subject: &str,
145        action_required: bool,
146        bytes: &[u8],
147    ) -> Result<JournalEntry, String> {
148        let hash = BlobStore::open(&self.storage_root)
149            .and_then(|store| store.put(bytes))
150            .map_err(|e| e.to_string())?;
151        let mut letter = GovernmentLetter::new(sender, subject, Self::now_unix() as u32);
152        letter.action_required = action_required;
153        letter.attachment_blob_hash = Some(hash);
154        let asserted = Self::now_unix() as u32;
155        let envelope =
156            build_government_letter_envelope(&letter, &self.owner_did, &self.author_did, asserted);
157        let summary = wellfare_core::welfare_support::government_letter_summary(&letter);
158        self.submit_record_with_summary(QAPP_WELFARE, envelope, SOURCE_WELFARE, Some(summary))?;
159        self.finalize_batch().ok();
160        self.latest_journal_entry()
161    }
162
163    /// All welfare-support journal rows (assistance needs, streams, government letters).
164    pub fn list_welfare_records(&self, limit: usize) -> Result<Vec<JournalEntry>, String> {
165        Ok(self
166            .list_health_records(limit)?
167            .into_iter()
168            .filter(|e| {
169                matches!(
170                    e.kind.as_str(),
171                    "assistance_need" | "welfare_stream" | "government_letter"
172                )
173            })
174            .collect())
175    }
176
177    // --- Cooperative work items (shared cooperative-core domain; plan §8, WP3) ---
178    //
179    // Work items persist through the same signed journal/policy path as WellFair records; a
180    // future dedicated cooperative service may take over persistence, but the domain types and
181    // derivations already live in `qualia-cooperative-core` so the Cooperative Qapp and the
182    // WellFair panels share one implementation.
183
184    /// Adds work-item.
185    pub fn add_work_item(&mut self, item: &WorkItem) -> Result<JournalEntry, String> {
186        let asserted = Self::now_unix() as u32;
187        let envelope = build_work_item_envelope(item, &self.owner_did, &self.author_did, asserted);
188        let summary = work_item_summary(item);
189        self.submit_record_with_summary(
190            QAPP_COOPERATIVE,
191            envelope,
192            SOURCE_COOPERATIVE,
193            Some(summary),
194        )?;
195        self.finalize_batch().ok();
196        self.latest_journal_entry()
197    }
198
199    /// Append an immutable status transition. The current status is a derived projection
200    /// (latest event), never a mutated field — so replayed transitions can't corrupt the board.
201    pub fn add_work_item_status(
202        &mut self,
203        event: &WorkItemStatusEvent,
204    ) -> Result<JournalEntry, String> {
205        let asserted = Self::now_unix() as u32;
206        let envelope =
207            build_work_item_status_envelope(event, &self.owner_did, &self.author_did, asserted);
208        let summary = work_item_status_summary(event);
209        self.submit_record_with_summary(
210            QAPP_COOPERATIVE,
211            envelope,
212            SOURCE_COOPERATIVE,
213            Some(summary),
214        )?;
215        self.finalize_batch().ok();
216        self.latest_journal_entry()
217    }
218
219    /// Lists work items.
220    pub fn list_work_items(&self, limit: usize) -> Result<Vec<JournalEntry>, String> {
221        self.list_journal_by_kind("work_item", limit)
222    }
223
224    /// Derive the Kanban board for a project from committed work items and their status events.
225    /// Pure over the unique-event-id set, so duplicate/replayed transitions never mis-place a card.
226    pub fn work_item_board(
227        &self,
228        project_id: &str,
229        limit: usize,
230    ) -> Result<Vec<BoardColumn>, String> {
231        let rows = self.list_health_records(limit)?;
232        let mut items = Vec::new();
233        let mut events = Vec::new();
234        for row in rows {
235            let Some(ref summary) = row.summary else {
236                continue;
237            };
238            match row.kind.as_str() {
239                "work_item" => {
240                    if let Some(item) = parse_work_item_summary(summary) {
241                        if item.project_id == project_id {
242                            items.push(item);
243                        }
244                    }
245                }
246                "work_item_status" => {
247                    if let Some(ev) = parse_work_item_status_summary(summary) {
248                        events.push(ev);
249                    }
250                }
251                _ => {}
252            }
253        }
254        Ok(derive_board(&items, &events))
255    }
256}