Skip to main content

folderbase_core/
availability.rs

1use std::time::Duration;
2
3/// The storage behavior selected for a folderbase on one device.
4#[derive(Debug, Clone, Copy, PartialEq, Eq)]
5pub enum StoragePolicy {
6    /// Materialize every current object, verify it, and never initiate eviction.
7    KeepLocal,
8    /// Materialize on demand, but still require an explicit archive decision
9    /// before removing local content.
10    Managed,
11    /// Treat the verified cloud copy as canonical for access on this device.
12    ///
13    /// Selecting this policy does not itself authorize deletion of existing
14    /// local bytes. Local removal still goes through [`evaluate_archive`].
15    CloudOnly,
16}
17
18#[derive(Debug, Clone, Copy, PartialEq, Eq)]
19pub enum FolderbaseLifecycle {
20    Active,
21    Paused,
22    Archived,
23}
24
25#[derive(Debug, Clone, Copy, PartialEq, Eq)]
26pub enum VerificationState {
27    Missing,
28    PresentUnverified,
29    Verified,
30}
31
32impl VerificationState {
33    fn is_verified(self) -> bool {
34        self == Self::Verified
35    }
36}
37
38/// Availability facts for one current knowledge object on one device.
39#[derive(Debug, Clone, PartialEq, Eq)]
40pub struct ObjectAvailability {
41    pub object_id: String,
42    pub bytes: u64,
43    pub local: VerificationState,
44    pub remote: VerificationState,
45    /// Whether this object is part of a currently declared task scope.
46    pub required_for_session: bool,
47    /// Whether the object has been protected from removal for that session.
48    pub pinned_for_session: bool,
49}
50
51#[derive(Debug, Clone, PartialEq, Eq)]
52pub struct AvailabilityInput<'a> {
53    pub policy: StoragePolicy,
54    pub lifecycle: FolderbaseLifecycle,
55    pub objects: &'a [ObjectAvailability],
56    /// A session may have an empty object set, so this cannot be inferred only
57    /// from `required_for_session`.
58    pub session_requested: bool,
59    /// Whether every required historical version has been verified remotely.
60    pub remote_history_verified: bool,
61    /// Whether the platform can honor the no-eviction Keep Local contract.
62    pub keep_local_guaranteed: bool,
63}
64
65#[derive(Debug, Clone, Copy, PartialEq, Eq)]
66pub enum ReadinessState {
67    LocalComplete,
68    SessionReady,
69    RemoteReady,
70    Incomplete,
71    Archived,
72}
73
74#[derive(Debug, Clone, PartialEq, Eq)]
75pub enum ReadinessBlocker {
76    Archived,
77    KeepLocalNotGuaranteed,
78    LocalObjectsMissing(u64),
79    LocalObjectsUnverified(u64),
80    SessionObjectsMissingOrUnverified(u64),
81    SessionObjectsUnpinned(u64),
82    RemoteObjectsMissingOrUnverified(u64),
83    RemoteHistoryUnverified,
84}
85
86#[derive(Debug, Clone, PartialEq, Eq)]
87pub struct ReadinessReport {
88    pub state: ReadinessState,
89    pub local_complete: bool,
90    pub session_ready: bool,
91    pub remote_ready: bool,
92    pub bytes_required_for_local_complete: u64,
93    pub missing_local_object_ids: Vec<String>,
94    pub unverified_local_object_ids: Vec<String>,
95    pub missing_remote_object_ids: Vec<String>,
96    pub unpinned_session_object_ids: Vec<String>,
97    pub blockers: Vec<ReadinessBlocker>,
98}
99
100/// Evaluate present readiness without materializing, uploading, or removing
101/// anything.
102pub fn evaluate_readiness(input: &AvailabilityInput<'_>) -> ReadinessReport {
103    if input.lifecycle == FolderbaseLifecycle::Archived {
104        return ReadinessReport {
105            state: ReadinessState::Archived,
106            local_complete: false,
107            session_ready: false,
108            remote_ready: false,
109            bytes_required_for_local_complete: input
110                .objects
111                .iter()
112                .filter(|object| !object.local.is_verified())
113                .fold(0_u64, |total, object| total.saturating_add(object.bytes)),
114            missing_local_object_ids: sorted_ids(
115                input
116                    .objects
117                    .iter()
118                    .filter(|object| object.local == VerificationState::Missing),
119            ),
120            unverified_local_object_ids: sorted_ids(
121                input
122                    .objects
123                    .iter()
124                    .filter(|object| object.local == VerificationState::PresentUnverified),
125            ),
126            missing_remote_object_ids: sorted_ids(
127                input
128                    .objects
129                    .iter()
130                    .filter(|object| !object.remote.is_verified()),
131            ),
132            unpinned_session_object_ids: sorted_ids(
133                input
134                    .objects
135                    .iter()
136                    .filter(|object| object.required_for_session && !object.pinned_for_session),
137            ),
138            blockers: vec![ReadinessBlocker::Archived],
139        };
140    }
141
142    let missing_local_object_ids = sorted_ids(
143        input
144            .objects
145            .iter()
146            .filter(|object| object.local == VerificationState::Missing),
147    );
148    let unverified_local_object_ids = sorted_ids(
149        input
150            .objects
151            .iter()
152            .filter(|object| object.local == VerificationState::PresentUnverified),
153    );
154    let missing_remote_object_ids = sorted_ids(
155        input
156            .objects
157            .iter()
158            .filter(|object| !object.remote.is_verified()),
159    );
160    let unpinned_session_object_ids = sorted_ids(
161        input
162            .objects
163            .iter()
164            .filter(|object| object.required_for_session && !object.pinned_for_session),
165    );
166
167    let all_local_verified = input
168        .objects
169        .iter()
170        .all(|object| object.local.is_verified());
171    let local_complete = all_local_verified
172        && (input.policy != StoragePolicy::KeepLocal || input.keep_local_guaranteed);
173    let session_objects_verified = input
174        .objects
175        .iter()
176        .filter(|object| object.required_for_session)
177        .all(|object| object.local.is_verified());
178    let session_objects_pinned = unpinned_session_object_ids.is_empty();
179    let session_ready =
180        input.session_requested && session_objects_verified && session_objects_pinned;
181    let remote_ready = missing_remote_object_ids.is_empty() && input.remote_history_verified;
182
183    let state = if session_ready {
184        ReadinessState::SessionReady
185    } else {
186        match input.policy {
187            StoragePolicy::KeepLocal if local_complete => ReadinessState::LocalComplete,
188            StoragePolicy::KeepLocal => ReadinessState::Incomplete,
189            StoragePolicy::Managed if local_complete => ReadinessState::LocalComplete,
190            StoragePolicy::Managed | StoragePolicy::CloudOnly if remote_ready => {
191                ReadinessState::RemoteReady
192            }
193            StoragePolicy::Managed | StoragePolicy::CloudOnly => ReadinessState::Incomplete,
194        }
195    };
196
197    let mut blockers = Vec::new();
198    if input.policy == StoragePolicy::KeepLocal && !input.keep_local_guaranteed {
199        blockers.push(ReadinessBlocker::KeepLocalNotGuaranteed);
200    }
201    if !missing_local_object_ids.is_empty() {
202        blockers.push(ReadinessBlocker::LocalObjectsMissing(
203            missing_local_object_ids.len() as u64,
204        ));
205    }
206    if !unverified_local_object_ids.is_empty() {
207        blockers.push(ReadinessBlocker::LocalObjectsUnverified(
208            unverified_local_object_ids.len() as u64,
209        ));
210    }
211    if input.session_requested && !session_objects_verified {
212        let count = input
213            .objects
214            .iter()
215            .filter(|object| object.required_for_session && !object.local.is_verified())
216            .count() as u64;
217        blockers.push(ReadinessBlocker::SessionObjectsMissingOrUnverified(count));
218    }
219    if input.session_requested && !session_objects_pinned {
220        blockers.push(ReadinessBlocker::SessionObjectsUnpinned(
221            unpinned_session_object_ids.len() as u64,
222        ));
223    }
224    if !missing_remote_object_ids.is_empty() {
225        blockers.push(ReadinessBlocker::RemoteObjectsMissingOrUnverified(
226            missing_remote_object_ids.len() as u64,
227        ));
228    }
229    if !input.remote_history_verified {
230        blockers.push(ReadinessBlocker::RemoteHistoryUnverified);
231    }
232
233    ReadinessReport {
234        state,
235        local_complete,
236        session_ready,
237        remote_ready,
238        bytes_required_for_local_complete: input
239            .objects
240            .iter()
241            .filter(|object| !object.local.is_verified())
242            .fold(0_u64, |total, object| total.saturating_add(object.bytes)),
243        missing_local_object_ids,
244        unverified_local_object_ids,
245        missing_remote_object_ids,
246        unpinned_session_object_ids,
247        blockers,
248    }
249}
250
251#[derive(Debug, Clone, Copy, PartialEq, Eq)]
252pub enum ArchiveRequest {
253    /// A one-time archive action initiated from an explicit member gesture.
254    Manual { approved_by_member: bool },
255    /// Evaluation of a member-configured inactivity policy.
256    Inactivity {
257        idle_for: Duration,
258        threshold: Duration,
259        /// The member previously opted into automatic execution for this
260        /// policy. When false, reaching the threshold creates a proposal.
261        automatic_execution_approved: bool,
262        /// Approval of this specific proposal.
263        proposal_approved_by_member: bool,
264    },
265}
266
267#[derive(Debug, Clone, Copy, PartialEq, Eq)]
268pub enum ArchiveDisposition {
269    Eligible,
270    ProposalEligible,
271    Blocked,
272}
273
274#[derive(Debug, Clone, PartialEq, Eq)]
275pub enum ArchiveBlocker {
276    AlreadyArchived,
277    AwaitingMemberApproval,
278    InactivityThresholdNotReached,
279    RemoteObjectsUnverified(u64),
280    RemoteHistoryUnverified,
281}
282
283#[derive(Debug, Clone, PartialEq, Eq)]
284pub struct ArchiveEligibility {
285    pub disposition: ArchiveDisposition,
286    /// The sole policy output that may authorize an executor to remove local
287    /// content. A storage policy by itself can never make this true.
288    pub may_remove_local_bytes: bool,
289    pub remotely_verified_bytes: u64,
290    pub expected_restore_bytes: u64,
291    pub blockers: Vec<ArchiveBlocker>,
292}
293
294/// Decide whether an archive may proceed. This function never removes bytes.
295///
296/// Remote verification is an invariant even for manually approved or
297/// explicitly automatic inactivity policies.
298pub fn evaluate_archive(
299    input: &AvailabilityInput<'_>,
300    request: ArchiveRequest,
301) -> ArchiveEligibility {
302    let remote_unverified_count = input
303        .objects
304        .iter()
305        .filter(|object| !object.remote.is_verified())
306        .count() as u64;
307    let remotely_verified_bytes = input
308        .objects
309        .iter()
310        .filter(|object| object.remote.is_verified())
311        .fold(0_u64, |total, object| total.saturating_add(object.bytes));
312    let expected_restore_bytes = input
313        .objects
314        .iter()
315        .fold(0_u64, |total, object| total.saturating_add(object.bytes));
316
317    let mut blockers = Vec::new();
318    if input.lifecycle == FolderbaseLifecycle::Archived {
319        blockers.push(ArchiveBlocker::AlreadyArchived);
320    }
321    if remote_unverified_count > 0 {
322        blockers.push(ArchiveBlocker::RemoteObjectsUnverified(
323            remote_unverified_count,
324        ));
325    }
326    if !input.remote_history_verified {
327        blockers.push(ArchiveBlocker::RemoteHistoryUnverified);
328    }
329
330    let threshold_reached;
331    let execution_approved;
332    match request {
333        ArchiveRequest::Manual { approved_by_member } => {
334            threshold_reached = true;
335            execution_approved = approved_by_member;
336            if !approved_by_member {
337                blockers.push(ArchiveBlocker::AwaitingMemberApproval);
338            }
339        }
340        ArchiveRequest::Inactivity {
341            idle_for,
342            threshold,
343            automatic_execution_approved,
344            proposal_approved_by_member,
345        } => {
346            threshold_reached = idle_for >= threshold;
347            execution_approved = automatic_execution_approved || proposal_approved_by_member;
348            if !threshold_reached {
349                blockers.push(ArchiveBlocker::InactivityThresholdNotReached);
350            } else if !execution_approved {
351                blockers.push(ArchiveBlocker::AwaitingMemberApproval);
352            }
353        }
354    }
355
356    let remote_verified = remote_unverified_count == 0 && input.remote_history_verified;
357    let may_remove_local_bytes = input.lifecycle != FolderbaseLifecycle::Archived
358        && remote_verified
359        && threshold_reached
360        && execution_approved;
361    let disposition = if may_remove_local_bytes {
362        ArchiveDisposition::Eligible
363    } else if input.lifecycle != FolderbaseLifecycle::Archived
364        && remote_verified
365        && threshold_reached
366        && !execution_approved
367    {
368        ArchiveDisposition::ProposalEligible
369    } else {
370        ArchiveDisposition::Blocked
371    };
372
373    ArchiveEligibility {
374        disposition,
375        may_remove_local_bytes,
376        remotely_verified_bytes,
377        expected_restore_bytes,
378        blockers,
379    }
380}
381
382fn sorted_ids<'a>(objects: impl Iterator<Item = &'a ObjectAvailability>) -> Vec<String> {
383    let mut ids: Vec<String> = objects.map(|object| object.object_id.clone()).collect();
384    ids.sort();
385    ids.dedup();
386    ids
387}
388
389#[cfg(test)]
390mod tests {
391    use super::*;
392
393    fn object(id: &str, local: VerificationState, remote: VerificationState) -> ObjectAvailability {
394        ObjectAvailability {
395            object_id: id.to_owned(),
396            bytes: 10,
397            local,
398            remote,
399            required_for_session: false,
400            pinned_for_session: false,
401        }
402    }
403
404    fn input<'a>(
405        objects: &'a [ObjectAvailability],
406        policy: StoragePolicy,
407    ) -> AvailabilityInput<'a> {
408        AvailabilityInput {
409            policy,
410            lifecycle: FolderbaseLifecycle::Active,
411            objects,
412            session_requested: false,
413            remote_history_verified: true,
414            keep_local_guaranteed: true,
415        }
416    }
417
418    #[test]
419    fn keep_local_requires_verified_content_and_a_platform_guarantee() {
420        let objects = vec![
421            object(
422                "z-missing",
423                VerificationState::Missing,
424                VerificationState::Verified,
425            ),
426            object(
427                "a-unverified",
428                VerificationState::PresentUnverified,
429                VerificationState::Verified,
430            ),
431        ];
432        let report = evaluate_readiness(&input(&objects, StoragePolicy::KeepLocal));
433
434        assert_eq!(report.state, ReadinessState::Incomplete);
435        assert!(!report.local_complete);
436        assert_eq!(report.bytes_required_for_local_complete, 20);
437        assert_eq!(report.missing_local_object_ids, ["z-missing"]);
438        assert_eq!(report.unverified_local_object_ids, ["a-unverified"]);
439
440        let verified = vec![object(
441            "one",
442            VerificationState::Verified,
443            VerificationState::Verified,
444        )];
445        let mut facts = input(&verified, StoragePolicy::KeepLocal);
446        assert_eq!(
447            evaluate_readiness(&facts).state,
448            ReadinessState::LocalComplete
449        );
450
451        facts.keep_local_guaranteed = false;
452        let not_guaranteed = evaluate_readiness(&facts);
453        assert_eq!(not_guaranteed.state, ReadinessState::Incomplete);
454        assert!(
455            not_guaranteed
456                .blockers
457                .contains(&ReadinessBlocker::KeepLocalNotGuaranteed)
458        );
459    }
460
461    #[test]
462    fn session_ready_requires_verified_and_pinned_scope() {
463        let mut objects = vec![
464            object(
465                "required",
466                VerificationState::Verified,
467                VerificationState::Missing,
468            ),
469            object(
470                "outside-scope",
471                VerificationState::Missing,
472                VerificationState::Missing,
473            ),
474        ];
475        objects[0].required_for_session = true;
476        let mut facts = input(&objects, StoragePolicy::Managed);
477        facts.session_requested = true;
478
479        assert!(!evaluate_readiness(&facts).session_ready);
480        objects[0].pinned_for_session = true;
481        let mut facts = input(&objects, StoragePolicy::Managed);
482        facts.session_requested = true;
483        let ready = evaluate_readiness(&facts);
484        assert_eq!(ready.state, ReadinessState::SessionReady);
485        assert!(ready.session_ready);
486        assert!(!ready.local_complete);
487    }
488
489    #[test]
490    fn cloud_only_reports_remote_ready_but_never_authorizes_eviction() {
491        let objects = vec![object(
492            "remote",
493            VerificationState::Missing,
494            VerificationState::Verified,
495        )];
496        let facts = input(&objects, StoragePolicy::CloudOnly);
497        let readiness = evaluate_readiness(&facts);
498        assert_eq!(readiness.state, ReadinessState::RemoteReady);
499
500        let archive = evaluate_archive(
501            &facts,
502            ArchiveRequest::Manual {
503                approved_by_member: false,
504            },
505        );
506        assert!(!archive.may_remove_local_bytes);
507        assert_eq!(archive.disposition, ArchiveDisposition::ProposalEligible);
508    }
509
510    #[test]
511    fn archive_requires_remote_verification_even_with_member_approval() {
512        let objects = vec![object(
513            "not-uploaded",
514            VerificationState::Verified,
515            VerificationState::Missing,
516        )];
517        let facts = input(&objects, StoragePolicy::Managed);
518        let decision = evaluate_archive(
519            &facts,
520            ArchiveRequest::Manual {
521                approved_by_member: true,
522            },
523        );
524
525        assert_eq!(decision.disposition, ArchiveDisposition::Blocked);
526        assert!(!decision.may_remove_local_bytes);
527        assert_eq!(
528            decision.blockers,
529            [ArchiveBlocker::RemoteObjectsUnverified(1)]
530        );
531    }
532
533    #[test]
534    fn inactivity_creates_a_proposal_unless_automatic_execution_was_approved() {
535        let objects = vec![object(
536            "safe",
537            VerificationState::Verified,
538            VerificationState::Verified,
539        )];
540        let facts = input(&objects, StoragePolicy::Managed);
541        let threshold = Duration::from_secs(90 * 24 * 60 * 60);
542
543        let early = evaluate_archive(
544            &facts,
545            ArchiveRequest::Inactivity {
546                idle_for: threshold - Duration::from_secs(1),
547                threshold,
548                automatic_execution_approved: true,
549                proposal_approved_by_member: false,
550            },
551        );
552        assert_eq!(early.disposition, ArchiveDisposition::Blocked);
553
554        let proposal = evaluate_archive(
555            &facts,
556            ArchiveRequest::Inactivity {
557                idle_for: threshold,
558                threshold,
559                automatic_execution_approved: false,
560                proposal_approved_by_member: false,
561            },
562        );
563        assert_eq!(proposal.disposition, ArchiveDisposition::ProposalEligible);
564        assert!(!proposal.may_remove_local_bytes);
565
566        let automatic = evaluate_archive(
567            &facts,
568            ArchiveRequest::Inactivity {
569                idle_for: threshold,
570                threshold,
571                automatic_execution_approved: true,
572                proposal_approved_by_member: false,
573            },
574        );
575        assert_eq!(automatic.disposition, ArchiveDisposition::Eligible);
576        assert!(automatic.may_remove_local_bytes);
577    }
578}