Skip to main content

dekopon_storage_host/
lib.rs

1//! ```compile_fail
2//! use dekopon_storage_host::StorageGrant;
3//!
4//! fn fabricate() -> StorageGrant {
5//!     StorageGrant { host_id: [0; 32] }
6//! }
7//! ```
8//! ```compile_fail
9//! use dekopon_storage_host::StorageGrant;
10//! fn require_clone<T: Clone>() {}
11//! fn main() { require_clone::<StorageGrant>(); }
12//! ```
13//! ```compile_fail
14//! use dekopon_storage_host::StorageGrant;
15//! use serde::Serialize;
16//! fn require_serialize<T: Serialize>() {}
17//! fn main() { require_serialize::<StorageGrant>(); }
18//! ```
19//! ```compile_fail
20//! use dekopon_storage_host::StorageGrant;
21//! use serde::de::DeserializeOwned;
22//! fn require_deserialize<T: DeserializeOwned>() {}
23//! fn main() { require_deserialize::<StorageGrant>(); }
24//! ```
25
26#![forbid(unsafe_code)]
27#![cfg_attr(test, allow(clippy::unwrap_used))]
28#![cfg_attr(
29    test,
30    allow(
31        clippy::disallowed_methods,
32        clippy::disallowed_types,
33        reason = "tests spawn, join and drain freely; production sites carry their own expectation"
34    )
35)]
36use parking_lot::{Mutex, MutexGuard};
37use std::{
38    collections::{BTreeMap, BTreeSet},
39    fmt,
40    fs::File,
41    path::{Component, Path, PathBuf},
42    sync::Arc,
43    time::{Duration, Instant},
44};
45
46use dekopon_capability::{StorageAccess, StorageInterface, StorageScope};
47use dekopon_core::{AgentId, CapabilityId, InvocationId, ProviderId, Subject};
48use serde::{Deserialize, Serialize};
49use thiserror::Error;
50
51mod config;
52mod handle;
53mod jsonl;
54mod key;
55mod layout;
56mod namespace;
57mod quota;
58mod sweep;
59mod vfs;
60
61pub use config::{StorageConfigError, StorageLimits};
62pub use handle::StorageHandle;
63pub use jsonl::JsonlChunk;
64pub use sweep::{RetentionPolicies, SweepSummary};
65pub use vfs::{Durability, FileStat, OpenOptions};
66
67use key::{
68    DOMAIN_AUDIT_SCOPE, DOMAIN_CONTENT, DOMAIN_DECISION_EVIDENCE, DOMAIN_NAMESPACE_PATH,
69    DOMAIN_RECORD_ID, commitment, random_bytes, token,
70};
71use layout::{Layout, scan_root_usage, scan_usage, usage_with_directory_entry};
72use namespace::{ContinuityOutcome, Namespace, NamespacePlan, Reset, deadline_after};
73use quota::QuotaLedger;
74
75#[derive(Clone, Copy, Debug, Default, Deserialize, Eq, PartialEq, Serialize)]
76#[serde(rename_all = "kebab-case")]
77pub enum ContinuityPolicy {
78    Relaxed,
79    #[default]
80    Paranoid,
81}
82
83#[derive(Clone, Copy, Debug, Eq, PartialEq)]
84pub enum ContinuityCheck {
85    Absent,
86    DigestMismatch,
87    SpaceBound,
88    RoutingDependent,
89    IdOnlySubject,
90    NoCandidate,
91}
92
93impl ContinuityCheck {
94    #[must_use]
95    pub const fn label(self) -> &'static str {
96        match self {
97            Self::Absent => "absent",
98            Self::DigestMismatch => "digest-mismatch",
99            Self::SpaceBound => "space-bound",
100            Self::RoutingDependent => "routing-dependent",
101            Self::IdOnlySubject => "id-only-subject",
102            Self::NoCandidate => "no-candidate",
103        }
104    }
105}
106
107#[derive(Clone, Copy, Debug, Default, Deserialize, Eq, PartialEq, Serialize)]
108#[serde(rename_all = "kebab-case")]
109pub enum UnprovenDisposition {
110    #[default]
111    Refuse,
112    FreshEpoch,
113}
114
115pub enum LegacyContinuity {
116    Unproven(ContinuityCheck),
117    Candidates(Vec<Vec<u8>>),
118}
119
120pub enum MemoryContinuity {
121    Relaxed,
122    Paranoid {
123        surface: Vec<u8>,
124        legacy: LegacyContinuity,
125        on_unproven: UnprovenDisposition,
126    },
127}
128
129pub(crate) enum Comparison {
130    Provider {
131        policy: ContinuityPolicy,
132        surface: Vec<u8>,
133    },
134    Memory(MemoryContinuity),
135}
136
137#[derive(Clone, Eq, PartialEq, Serialize, Deserialize)]
138#[serde(transparent)]
139pub struct StorageScopeCommitment(String);
140
141impl StorageScopeCommitment {
142    #[must_use]
143    pub fn as_str(&self) -> &str {
144        &self.0
145    }
146}
147
148impl fmt::Debug for StorageScopeCommitment {
149    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
150        formatter.write_str("StorageScopeCommitment([REDACTED])")
151    }
152}
153
154#[derive(Clone, Debug, Default, Deserialize, Eq, PartialEq, Serialize)]
155#[serde(deny_unknown_fields, rename_all = "camelCase")]
156pub struct StorageEvidence {
157    pub operations: u64,
158    pub syncs: u64,
159    pub quota_denials: u64,
160    pub read_bytes: u64,
161    pub write_bytes: u64,
162    pub evidence_commitment: String,
163}
164
165pub struct StorageGrantRequest {
166    invocation: InvocationId,
167    capability: CapabilityId,
168    provider: ProviderId,
169    interface: StorageInterface,
170    access: StorageAccess,
171    scope: StorageScope,
172    agent: AgentId,
173    subject: Subject,
174    transport_kind: String,
175    transport: String,
176    channel: String,
177    conversation: String,
178    comparison: Comparison,
179    shared_namespace: Option<ProviderId>,
180    space_key: Option<dekopon_core::SpaceKey>,
181}
182
183impl fmt::Debug for StorageGrantRequest {
184    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
185        formatter.write_str("StorageGrantRequest([REDACTED])")
186    }
187}
188
189impl StorageGrantRequest {
190    #[expect(
191        clippy::too_many_arguments,
192        reason = "reshaped by the unit that next rewrites this"
193    )]
194    pub fn new(
195        invocation: InvocationId,
196        capability: CapabilityId,
197        provider: ProviderId,
198        interface: StorageInterface,
199        access: StorageAccess,
200        scope: StorageScope,
201        agent: AgentId,
202        subject: Subject,
203        transport_kind: impl Into<String>,
204        transport: impl Into<String>,
205        channel: impl Into<String>,
206        conversation: impl Into<String>,
207        continuity_policy: ContinuityPolicy,
208        authority_surface: Vec<u8>,
209    ) -> Self {
210        Self {
211            invocation,
212            capability,
213            provider,
214            interface,
215            access,
216            scope,
217            agent,
218            subject,
219            transport_kind: transport_kind.into(),
220            transport: transport.into(),
221            channel: channel.into(),
222            conversation: conversation.into(),
223            comparison: Comparison::Provider {
224                policy: continuity_policy,
225                surface: authority_surface,
226            },
227            shared_namespace: None,
228            space_key: None,
229        }
230    }
231
232    #[must_use]
233    pub fn with_shared_namespace(mut self, namespace: Option<ProviderId>) -> Self {
234        self.shared_namespace = namespace;
235        self
236    }
237
238    #[must_use]
239    pub fn with_memory_continuity(mut self, continuity: MemoryContinuity) -> Self {
240        self.comparison = Comparison::Memory(continuity);
241        self
242    }
243
244    #[must_use]
245    pub fn with_space_key(mut self, key: Option<dekopon_core::SpaceKey>) -> Self {
246        self.space_key = key;
247        self
248    }
249
250    pub(crate) fn scope_values(&self) -> Vec<String> {
251        let provider = self
252            .shared_namespace
253            .as_ref()
254            .unwrap_or(&self.provider)
255            .to_string();
256        let agent = self.agent.to_string();
257        match self.scope {
258            StorageScope::PrivateConversation => vec![
259                provider,
260                agent,
261                self.subject.canonical(),
262                self.transport_kind.clone(),
263                self.transport.clone(),
264                self.channel.clone(),
265                self.conversation.clone(),
266            ],
267            StorageScope::SharedConversation => vec![
268                "shared-conversation-v1".to_owned(),
269                provider,
270                agent,
271                self.transport_kind.clone(),
272                self.transport.clone(),
273                self.channel.clone(),
274                self.conversation.clone(),
275            ],
276            StorageScope::Agent => vec!["agent-v1".to_owned(), provider, agent],
277            StorageScope::Space => vec![
278                "space-v1".to_owned(),
279                provider,
280                self.space_key.as_ref().map_or_else(String::new, |key| {
281                    key.encode()
282                        .iter()
283                        .map(|byte| format!("{byte:02x}"))
284                        .collect()
285                }),
286            ],
287        }
288    }
289    pub(crate) fn scope(&self) -> StorageScope {
290        self.scope
291    }
292    pub(crate) const fn comparison(&self) -> &Comparison {
293        &self.comparison
294    }
295}
296
297pub struct StorageGrantPreparation {
298    host: StorageHost,
299    request: StorageGrantRequest,
300    base_token: String,
301    scope_commitment: StorageScopeCommitment,
302}
303
304impl fmt::Debug for StorageGrantPreparation {
305    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
306        formatter.write_str("StorageGrantPreparation([REDACTED])")
307    }
308}
309
310impl StorageGrantPreparation {
311    #[must_use]
312    pub fn scope_commitment(&self) -> StorageScopeCommitment {
313        self.scope_commitment.clone()
314    }
315
316    #[must_use]
317    pub fn namespace(&self) -> &str {
318        &self.base_token
319    }
320
321    #[must_use]
322    pub fn record_id(&self, delivery: &[u8]) -> String {
323        record_id(&self.base_token, delivery)
324    }
325
326    #[must_use]
327    pub fn evidence_commitment(&self, label: &str, bytes: &[u8]) -> String {
328        commitment(
329            DOMAIN_DECISION_EVIDENCE,
330            &[self.base_token.as_bytes(), label.as_bytes(), bytes],
331        )
332    }
333
334    #[must_use]
335    pub fn content_commitment(&self, user: &str, assistant: &str) -> String {
336        content_commitment(&self.base_token, user, assistant)
337    }
338
339    pub fn materialize(self) -> Result<StorageGrant, StorageHostError> {
340        self.host.materialize_grant(self.request, self.base_token)
341    }
342}
343
344pub struct StorageGrant {
345    host_id: [u8; 32],
346    invocation: InvocationId,
347    capability: CapabilityId,
348    provider: ProviderId,
349    shared_namespace: Option<ProviderId>,
350    interface: StorageInterface,
351    access: StorageAccess,
352    scope_kind: StorageScope,
353    namespace: Namespace,
354    limits: StorageLimits,
355}
356
357impl fmt::Debug for StorageGrant {
358    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
359        formatter.write_str("StorageGrant([REDACTED])")
360    }
361}
362
363impl StorageGrant {
364    #[must_use]
365    pub fn invocation(&self) -> &InvocationId {
366        &self.invocation
367    }
368    #[must_use]
369    pub fn capability(&self) -> &CapabilityId {
370        &self.capability
371    }
372    #[must_use]
373    pub fn provider(&self) -> &ProviderId {
374        &self.provider
375    }
376    #[must_use]
377    pub fn shared_namespace(&self) -> Option<&ProviderId> {
378        self.shared_namespace.as_ref()
379    }
380    #[must_use]
381    pub const fn interface(&self) -> StorageInterface {
382        self.interface
383    }
384    #[must_use]
385    pub const fn access(&self) -> StorageAccess {
386        self.access
387    }
388    #[must_use]
389    pub const fn scope(&self) -> StorageScope {
390        self.scope_kind
391    }
392    #[must_use]
393    pub fn scope_commitment(&self) -> StorageScopeCommitment {
394        StorageScopeCommitment(self.namespace.scope_commitment.clone())
395    }
396    #[must_use]
397    pub fn record_id(&self, delivery: &[u8]) -> String {
398        record_id(&self.namespace.base_token, delivery)
399    }
400    #[must_use]
401    pub fn evidence_commitment(&self, label: &str, bytes: &[u8]) -> String {
402        commitment(
403            DOMAIN_DECISION_EVIDENCE,
404            &[
405                self.namespace.base_token.as_bytes(),
406                label.as_bytes(),
407                bytes,
408            ],
409        )
410    }
411
412    #[must_use]
413    pub fn content_commitment(&self, user: &str, assistant: &str) -> String {
414        content_commitment(&self.namespace.base_token, user, assistant)
415    }
416}
417
418fn record_id(base_token: &str, delivery: &[u8]) -> String {
419    commitment(DOMAIN_RECORD_ID, &[base_token.as_bytes(), delivery])
420}
421
422fn content_commitment(base_token: &str, user: &str, assistant: &str) -> String {
423    commitment(
424        DOMAIN_CONTENT,
425        &[base_token.as_bytes(), user.as_bytes(), assistant.as_bytes()],
426    )
427}
428
429#[derive(Debug)]
430struct HostInner {
431    id: [u8; 32],
432    layout: Layout,
433    ledger: Arc<QuotaLedger>,
434    limits: StorageLimits,
435    namespace_locks: Mutex<BTreeMap<String, Arc<Mutex<()>>>>,
436    namespace_observation_lock: Mutex<()>,
437}
438
439#[derive(Clone)]
440pub struct StorageHost {
441    inner: Arc<HostInner>,
442}
443
444impl fmt::Debug for StorageHost {
445    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
446        formatter.write_str("StorageHost([REDACTED])")
447    }
448}
449
450impl StorageHost {
451    pub fn open(root: impl AsRef<Path>, limits: StorageLimits) -> Result<Self, StorageHostError> {
452        limits.validate()?;
453        let root = resolve_storage_root_path(root.as_ref())?;
454        let minimum = Layout::minimum_usage(&root)?;
455        if minimum.bytes > limits.max_root_bytes || minimum.entries > limits.startup_max_entries {
456            return Err(StorageHostError::QuotaExceeded);
457        }
458        let layout = Layout::open(&root)?;
459        let (usage, namespace_count) = scan_root_usage(&layout, limits.startup_max_entries)?;
460        if usage.bytes > limits.max_root_bytes {
461            return Err(StorageHostError::QuotaExceeded);
462        }
463        tracing::info!(
464            event = "storage_namespace_capacity",
465            storage.namespace.count = namespace_count,
466            storage.namespace.limit = limits.max_namespaces,
467            "storage.namespace.capacity"
468        );
469        let ledger = QuotaLedger::new(limits.clone(), usage);
470        #[allow(
471            clippy::map_err_ignore,
472            reason = "the discarded value is the rejected raw-entropy Vec<u8> itself, whose only \
473                      reportable property is the length EntropyLength already names"
474        )]
475        let id: [u8; 32] = random_bytes(32)?
476            .try_into()
477            .map_err(|_| StorageHostError::EntropyLength)?;
478        Ok(Self {
479            inner: Arc::new(HostInner {
480                id,
481                layout,
482                ledger,
483                limits,
484                namespace_locks: Mutex::new(BTreeMap::new()),
485                namespace_observation_lock: Mutex::new(()),
486            }),
487        })
488    }
489
490    #[must_use]
491    pub fn evidence_commitment(&self, label: &str, bytes: &[u8]) -> String {
492        commitment(
493            DOMAIN_DECISION_EVIDENCE,
494            &[b"denied-storage", label.as_bytes(), bytes],
495        )
496    }
497
498    pub fn prepare_grant(
499        &self,
500        request: StorageGrantRequest,
501    ) -> Result<StorageGrantPreparation, StorageHostError> {
502        if request.scope == StorageScope::Space
503            && !request
504                .space_key
505                .as_ref()
506                .is_some_and(|key| key.agent == request.agent)
507        {
508            return Err(StorageHostError::InvalidArgument);
509        }
510        let values = request.scope_values();
511        let fields = values.iter().map(String::as_bytes).collect::<Vec<_>>();
512        Ok(StorageGrantPreparation {
513            host: self.clone(),
514            base_token: token(DOMAIN_NAMESPACE_PATH, &fields),
515            scope_commitment: StorageScopeCommitment(commitment(DOMAIN_AUDIT_SCOPE, &fields)),
516            request,
517        })
518    }
519
520    pub fn grant(&self, request: StorageGrantRequest) -> Result<StorageGrant, StorageHostError> {
521        self.prepare_grant(request)?.materialize()
522    }
523
524    fn materialize_grant(
525        &self,
526        request: StorageGrantRequest,
527        base: String,
528    ) -> Result<StorageGrant, StorageHostError> {
529        debug_assert_eq!(
530            base,
531            token(
532                DOMAIN_NAMESPACE_PATH,
533                &request
534                    .scope_values()
535                    .iter()
536                    .map(String::as_bytes)
537                    .collect::<Vec<_>>()
538            )
539        );
540        // One deadline covers all of a grant's waits; per-wait timeouts would let the k-th
541        // contender behind the lease wait k times as long.
542        let deadline = deadline_after(self.inner.limits.lock_timeout_ms)?;
543        let namespace_lock = namespace_lock(&self.inner.namespace_locks, &base);
544        let _namespace = lock_before(&namespace_lock, deadline)?;
545        let mut namespace_reservation = Some({
546            // The observation lock is dropped before any base lease wait, preserving concurrency
547            // between distinct namespaces.
548            let _observation = self.inner.namespace_observation_lock.lock();
549            let observed_namespaces = self
550                .inner
551                .layout
552                .namespaces()
553                .entries_bounded(self.inner.limits.startup_max_entries)?
554                .into_iter()
555                .collect::<BTreeSet<_>>();
556            self.inner
557                .ledger
558                .reserve_namespace(base.clone(), observed_namespaces)?
559        });
560        // Rescanning here would race another namespace's commit, publishing a stale lower total
561        // after that commit releases its reservation.
562        let mut plan = NamespacePlan::prepare(
563            self.inner.layout.namespaces(),
564            &request,
565            deadline,
566            self.inner.limits.startup_max_entries,
567        )?;
568        let reset = plan.take_reset();
569        let continuity = plan.take_continuity();
570        if plan.maximum_generation_peak_bytes() > self.inner.limits.max_namespace_bytes {
571            return Err(StorageHostError::QuotaExceeded);
572        }
573        let before_namespace = plan.before_usage();
574        let housekeeping_reservation = self
575            .inner
576            .ledger
577            .reserve_root(plan.reserved_bytes(), plan.reserved_entries())?;
578        // This critical section must stay free of lease waits, or it would serialize an unrelated
579        // namespace behind a blocked lease.
580        let _observation = self.inner.namespace_observation_lock.lock();
581        self.inner.ledger.observe_namespaces(
582            self.inner
583                .layout
584                .namespaces()
585                .entries_bounded(self.inner.limits.startup_max_entries)?,
586        );
587        let namespace = match plan.apply(self.inner.layout.namespaces(), deadline) {
588            Ok(namespace) => namespace,
589            Err(error) => {
590                // A namespace mutation may partially complete before failing, so a physically
591                // present base still owns its slot afterward.
592                if self.inner.layout.namespaces().exists(&base).unwrap_or(true) {
593                    namespace_reservation
594                        .take()
595                        .expect("namespace reservation")
596                        .commit();
597                }
598                housekeeping_reservation.retain();
599                return Err(error);
600            }
601        };
602        let base_directory = match self.inner.layout.namespaces().open_directory(&base) {
603            Ok(directory) => directory,
604            Err(error) => {
605                namespace_reservation
606                    .take()
607                    .expect("namespace reservation")
608                    .commit();
609                housekeeping_reservation.retain();
610                return Err(error);
611            }
612        };
613        let scanned = match scan_usage(&base_directory, self.inner.limits.startup_max_entries) {
614            Ok(usage) => usage,
615            Err(error) => {
616                namespace_reservation
617                    .take()
618                    .expect("namespace reservation")
619                    .commit();
620                housekeeping_reservation.retain();
621                return Err(error);
622            }
623        };
624        let after_namespace = match usage_with_directory_entry(scanned) {
625            Ok(usage) => usage,
626            Err(error) => {
627                namespace_reservation
628                    .take()
629                    .expect("namespace reservation")
630                    .commit();
631                housekeeping_reservation.retain();
632                return Err(error);
633            }
634        };
635        if let Err(error) = housekeeping_reservation.commit(before_namespace, after_namespace) {
636            namespace_reservation
637                .take()
638                .expect("namespace reservation")
639                .commit();
640            return Err(error);
641        }
642        namespace_reservation
643            .take()
644            .expect("namespace reservation")
645            .commit();
646        if let Some(cause) = reset {
647            return Err(report_namespace_reset(cause, &namespace));
648        }
649        match continuity {
650            Some(ContinuityOutcome::Migrated) => tracing::info!(
651                event = "storage_continuity_migrated",
652                category = "storage",
653                storage.namespace = %namespace.base_token,
654                storage.generation = %namespace.generation_token,
655                "storage.continuity.migrated"
656            ),
657            Some(ContinuityOutcome::FreshEpoch { check }) => tracing::warn!(
658                event = "storage_continuity_fresh_epoch",
659                category = "storage",
660                storage.namespace = %namespace.base_token,
661                storage.generation = %namespace.generation_token,
662                storage.continuity.check = check.label(),
663                "storage.continuity.fresh_epoch"
664            ),
665            None => {}
666        }
667        Ok(StorageGrant {
668            host_id: self.inner.id,
669            invocation: request.invocation,
670            capability: request.capability,
671            provider: request.provider,
672            shared_namespace: request.shared_namespace,
673            interface: request.interface,
674            access: request.access,
675            scope_kind: request.scope,
676            namespace,
677            limits: self.inner.limits.clone(),
678        })
679    }
680
681    pub fn begin(&self, grant: StorageGrant) -> Result<StorageHandle, StorageHostError> {
682        if grant.host_id != self.inner.id {
683            return Err(StorageHostError::GrantHostMismatch);
684        }
685        StorageHandle::begin(grant, Arc::clone(&self.inner.ledger))
686    }
687
688    #[must_use]
689    pub fn limits(&self) -> &StorageLimits {
690        &self.inner.limits
691    }
692}
693
694fn lock_before(
695    lock: &Mutex<()>,
696    deadline: Instant,
697) -> Result<MutexGuard<'_, ()>, StorageHostError> {
698    loop {
699        match lock.try_lock() {
700            Some(guard) => return Ok(guard),
701            None if Instant::now() < deadline => {
702                std::thread::sleep(Duration::from_millis(5));
703            }
704            None => return Err(StorageHostError::Timeout),
705        }
706    }
707}
708
709fn namespace_lock(
710    registry: &Mutex<BTreeMap<String, Arc<Mutex<()>>>>,
711    base: &str,
712) -> Arc<Mutex<()>> {
713    let mut locks = registry.lock();
714    locks.retain(|_, lock| Arc::strong_count(lock) > 1);
715    Arc::clone(
716        locks
717            .entry(base.to_owned())
718            .or_insert_with(|| Arc::new(Mutex::new(()))),
719    )
720}
721
722pub fn resolve_storage_root_path(path: &Path) -> Result<PathBuf, StorageHostError> {
723    let io_error = |path: &Path, source: std::io::Error| StorageHostError::RootIo {
724        path: path.to_path_buf(),
725        source,
726    };
727    let unsafe_path = |path: &Path| StorageHostError::UnsafeRoot {
728        path: path.to_path_buf(),
729    };
730    let absolute = if path.is_absolute() {
731        path.to_path_buf()
732    } else {
733        std::env::current_dir()
734            .map_err(|source| io_error(path, source))?
735            .join(path)
736    };
737    let mut components = Vec::new();
738    for component in absolute.components() {
739        match component {
740            Component::RootDir | Component::CurDir => {}
741            Component::Normal(component) => components.push(component.to_os_string()),
742            Component::ParentDir | Component::Prefix(_) => return Err(unsafe_path(&absolute)),
743        }
744    }
745    if components.is_empty() {
746        return Err(unsafe_path(&absolute));
747    }
748
749    let root_fd = rustix::fs::open(
750        "/",
751        rustix::fs::OFlags::RDONLY
752            | rustix::fs::OFlags::DIRECTORY
753            | rustix::fs::OFlags::NOFOLLOW
754            | rustix::fs::OFlags::CLOEXEC,
755        rustix::fs::Mode::empty(),
756    )
757    .map_err(|source| io_error(Path::new("/"), std::io::Error::from(source)))?;
758    let mut directory = File::from(root_fd);
759    let mut traversed = PathBuf::from("/");
760    for component in &components[..components.len() - 1] {
761        traversed.push(component);
762        let fd = rustix::fs::openat(
763            &directory,
764            component,
765            rustix::fs::OFlags::RDONLY
766                | rustix::fs::OFlags::DIRECTORY
767                | rustix::fs::OFlags::NOFOLLOW
768                | rustix::fs::OFlags::CLOEXEC,
769            rustix::fs::Mode::empty(),
770        )
771        .map_err(|source| io_error(&traversed, std::io::Error::from(source)))?;
772        directory = File::from(fd);
773    }
774    traversed.push(components.last().expect("non-empty path components"));
775    Ok(traversed)
776}
777
778fn report_namespace_reset(reset: Reset, fresh: &Namespace) -> StorageHostError {
779    tracing::error!(
780        event = "storage_namespace_reset",
781        category = "storage",
782        storage.namespace = %fresh.base_token,
783        storage.generation = %fresh.generation_token,
784        storage.previous_generation = reset.previous_generation.as_deref(),
785        storage.check = reset.check,
786        storage.path = reset
787            .path
788            .as_deref()
789            .map(|path| tracing::field::display(path.display())),
790        "storage.namespace.reset"
791    );
792    StorageHostError::Corrupt {
793        scope: reset.check,
794        site: Some(Box::new(CorruptionSite {
795            namespace: Some(fresh.base_token.clone()),
796            generation: reset.previous_generation,
797            path: reset.path,
798            reset: Some(fresh.generation_token.clone()),
799        })),
800    }
801}
802
803pub(crate) fn report_decode_failure(document: &'static str, error: &serde_json::Error) {
804    tracing::warn!(
805        event = "storage_document_decode_failed",
806        category = "storage",
807        storage.document = document,
808        decode.class = ?error.classify(),
809        decode.line = error.line(),
810        decode.column = error.column(),
811        "storage.document.decode.failed"
812    );
813}
814
815#[derive(Clone, Copy, Debug, Eq, Ord, PartialEq, PartialOrd)]
816pub enum StorageFailureClass {
817    Quota,
818    Timeout,
819    Corrupt,
820    Denied,
821    Io,
822}
823
824impl StorageFailureClass {
825    #[must_use]
826    pub const fn label(self) -> &'static str {
827        match self {
828            Self::Quota => "quota",
829            Self::Timeout => "timeout",
830            Self::Corrupt => "corrupt",
831            Self::Denied => "denied",
832            Self::Io => "io",
833        }
834    }
835}
836
837impl std::fmt::Display for StorageFailureClass {
838    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
839        formatter.write_str(self.label())
840    }
841}
842
843#[derive(Debug, Error)]
844pub enum StorageHostError {
845    #[error(transparent)]
846    Configuration(#[from] StorageConfigError),
847    #[error("storage root input/output failed at {}", path.display())]
848    RootIo {
849        path: PathBuf,
850        #[source]
851        source: std::io::Error,
852    },
853    #[error("storage root or ancestor is unsafe: {}", path.display())]
854    UnsafeRoot { path: PathBuf },
855    #[error("another conforming storage writer holds the root")]
856    SecondWriter,
857    #[error("storage layout is corrupt: {}", path.display())]
858    CorruptLayout { path: PathBuf },
859    #[error("storage corruption detected: {scope}{}", SiteSuffix(.site))]
860    Corrupt {
861        scope: &'static str,
862        site: Option<Box<CorruptionSite>>,
863    },
864    #[error("storage quota exceeded")]
865    QuotaExceeded,
866    #[error("storage resource is busy")]
867    Busy,
868    #[error("storage operation timed out")]
869    Timeout,
870    #[error("storage permission denied")]
871    PermissionDenied,
872    #[error("storage logical name is invalid")]
873    InvalidName,
874    #[error("storage argument is invalid")]
875    InvalidArgument,
876    #[error("storage object was not found")]
877    NotFound,
878    #[error("storage object already exists")]
879    AlreadyExists,
880    #[error("storage operation is unsupported")]
881    Unsupported,
882    #[error("storage input/output failed")]
883    Io,
884    #[error("storage arithmetic overflowed")]
885    Arithmetic,
886    #[error("storage entropy failed")]
887    Entropy {
888        #[source]
889        source: std::io::Error,
890    },
891    #[error("storage entropy returned an invalid length")]
892    EntropyLength,
893    #[error("storage clock failed")]
894    Clock,
895    #[error("storage startup scan saw {count} entries, above {maximum}")]
896    StartupEntryLimit { count: u64, maximum: u64 },
897    #[error("storage grant belongs to another host instance")]
898    GrantHostMismatch,
899    #[error("broker memory continuity could not be proved: {}", check.label())]
900    ContinuityUnproven { check: ContinuityCheck },
901}
902
903#[derive(Clone, Debug, Default, Eq, PartialEq)]
904pub struct CorruptionSite {
905    pub namespace: Option<String>,
906    pub generation: Option<String>,
907    pub path: Option<PathBuf>,
908    pub reset: Option<String>,
909}
910
911struct SiteSuffix<'a>(&'a Option<Box<CorruptionSite>>);
912
913impl fmt::Display for SiteSuffix<'_> {
914    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
915        let Some(site) = self.0 else {
916            return Ok(());
917        };
918        if let Some(namespace) = &site.namespace {
919            write!(formatter, " in namespace {namespace}")?;
920        }
921        if let Some(generation) = &site.generation {
922            write!(formatter, " generation {generation}")?;
923        }
924        if let Some(path) = &site.path {
925            write!(formatter, " at {}", path.display())?;
926        }
927        if let Some(reset) = &site.reset {
928            write!(formatter, "; reset to generation {reset}")?;
929        }
930        Ok(())
931    }
932}
933
934impl StorageHostError {
935    #[must_use]
936    pub const fn corrupt(scope: &'static str) -> Self {
937        Self::Corrupt { scope, site: None }
938    }
939
940    #[expect(
941        clippy::wildcard_enum_match_arm,
942        reason = "reshaped by the unit that next rewrites this"
943    )]
944    fn site_mut(&mut self) -> Option<&mut CorruptionSite> {
945        match self {
946            Self::Corrupt { site, .. } => Some(site.get_or_insert_with(Box::default)),
947            _ => None,
948        }
949    }
950
951    pub(crate) fn at(mut self, entry: PathBuf) -> Self {
952        if let Some(site) = self.site_mut() {
953            site.path.get_or_insert(entry);
954        }
955        self
956    }
957
958    pub(crate) fn in_namespace(mut self, base: &str, generation_token: Option<&str>) -> Self {
959        if let Some(site) = self.site_mut() {
960            site.namespace.get_or_insert_with(|| base.to_owned());
961            if let Some(token) = generation_token {
962                site.generation.get_or_insert_with(|| token.to_owned());
963            }
964        }
965        self
966    }
967
968    #[must_use]
969    pub fn namespace_reset(&self) -> bool {
970        matches!(self, Self::Corrupt { site: Some(site), .. } if site.reset.is_some())
971    }
972
973    #[must_use]
974    #[expect(
975        clippy::wildcard_enum_match_arm,
976        reason = "reshaped by the unit that next rewrites this"
977    )]
978    pub const fn class(&self) -> StorageFailureClass {
979        match self {
980            Self::QuotaExceeded | Self::Arithmetic => StorageFailureClass::Quota,
981            Self::Timeout => StorageFailureClass::Timeout,
982            Self::Corrupt { .. } | Self::CorruptLayout { .. } => StorageFailureClass::Corrupt,
983            Self::PermissionDenied | Self::GrantHostMismatch | Self::ContinuityUnproven { .. } => {
984                StorageFailureClass::Denied
985            }
986            _ => StorageFailureClass::Io,
987        }
988    }
989}