fix(openapi): harden story 2.1 production lifecycle

crates/crank-artifacts/src/housekeeping.rs

@@ -4,7 +4,7 @@ use std::{
     time::{Duration, SystemTime, UNIX_EPOCH},
 };
 
-use crate::temp_scan::{list_names, valid_temp_name};
+use crate::temp_scan::{list_names_after, valid_temp_name};
 use crate::{
     ArtifactError, ArtifactStore, ReconciliationMutation, ReconciliationNamespace,
     ReconciliationScan, ReconciliationScanStop,
@@ -94,10 +94,33 @@ pub struct StaleTemp {
     grace: Duration,
 }
 
+/// Opaque, inode-bound progress marker for the bounded stale-temp sweeper.
+///
+/// It deliberately advances by shard instead of retaining a directory offset:
+/// directory offsets are invalidated by a concurrent writer, while round-robin
+/// shard progress prevents a busy low-numbered shard from starving all others.
+#[derive(Clone, Debug)]
+pub struct TempScanCursor {
+    root_dev: u64,
+    root_ino: u64,
+    next_shard: u8,
+    shard_continuation: Option<TempShardContinuation>,
+}
+
+#[derive(Clone, Debug)]
+struct TempShardContinuation {
+    shard: u8,
+    dev: u64,
+    ino: u64,
+    cookie: i64,
+}
+
 #[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
 pub struct TempScan {
     pub scanned: usize,
     pub omitted: usize,
+    /// True when this page completed a full round-robin traversal.
+    pub complete: bool,
 }
 
 impl ArtifactStore {
@@ -324,27 +347,93 @@ impl ArtifactStore {
         scan_budget: usize,
         result_limit: usize,
     ) -> Result<(TempScan, Vec<StaleTemp>), ArtifactError> {
+        self.scan_stale_temps_after(grace, None, scan_budget, result_limit)
+            .map(|(report, candidates, _)| (report, candidates))
+    }
+
+    /// Resumes stale-temp cleanup from an opaque round-robin marker. A
+    /// continuation is valid only for this exact pinned root.
+    pub fn scan_stale_temps_after(
+        &self,
+        grace: Duration,
+        continuation: Option<TempScanCursor>,
+        scan_budget: usize,
+        result_limit: usize,
+    ) -> Result<(TempScan, Vec<StaleTemp>, TempScanCursor), ArtifactError> {
         let root = self.root()?;
         let _lock = RootLock::shared(root)?;
         ensure_root_unchanged(root)?;
         let sha = match open_existing_dir(root.fd.as_raw_fd(), b"sha256") {
             Ok(fd) => fd,
-            Err(ArtifactError::NotFound) => return Ok((TempScan::default(), Vec::new())),
+            Err(ArtifactError::NotFound) => {
+                return Ok((
+                    TempScan {
+                        complete: true,
+                        ..TempScan::default()
+                    },
+                    Vec::new(),
+                    TempScanCursor {
+                        root_dev: root.dev,
+                        root_ino: root.ino,
+                        next_shard: 0,
+                        shard_continuation: None,
+                    },
+                ));
+            }
             Err(error) => return Err(error),
         };
+        let (start_shard, mut shard_continuation) = match continuation {
+            Some(cursor) if cursor.root_dev == root.dev && cursor.root_ino == root.ino => {
+                (cursor.next_shard, cursor.shard_continuation)
+            }
+            Some(_) => return Err(ArtifactError::UnsafeRoot),
+            None => (0, None),
+        };
         let mut report = TempScan::default();
         let mut remaining = scan_budget;
         let mut result = Vec::new();
-        for shard in (0_u8..=255).map(|value| format!("{value:02x}")) {
+        if remaining == 0 {
+            return Ok((
+                report,
+                result,
+                TempScanCursor {
+                    root_dev: root.dev,
+                    root_ino: root.ino,
+                    next_shard: start_shard,
+                    shard_continuation,
+                },
+            ));
+        }
+        let mut next_shard = start_shard;
+        for offset in 0_u16..=255 {
             if remaining == 0 {
                 break;
             }
+            let shard_number = start_shard.wrapping_add(offset as u8);
+            next_shard = shard_number.wrapping_add(1);
+            let shard = format!("{shard_number:02x}");
             let shard_fd = match open_existing_dir(sha.as_raw_fd(), shard.as_bytes()) {
                 Ok(fd) => fd,
-                Err(ArtifactError::NotFound) => continue,
+                Err(ArtifactError::NotFound) => {
+                    shard_continuation = None;
+                    continue;
+                }
                 Err(error) => return Err(error),
             };
-            for name in list_names(shard_fd.as_raw_fd(), &mut remaining, &mut report)? {
+            let stat = stat_fd(shard_fd.as_raw_fd())?;
+            let resume = shard_continuation.take().and_then(|continuation| {
+                if continuation.shard == shard_number
+                    && continuation.dev == stat.st_dev
+                    && continuation.ino == stat.st_ino
+                {
+                    Some(continuation.cookie)
+                } else {
+                    None
+                }
+            });
+            let page = list_names_after(shard_fd.as_raw_fd(), &mut remaining, &mut report, resume)?;
+            for entry in page.names {
+                let name = entry.name;
                 if !valid_temp_name(&name) {
                     continue;
                 }
@@ -370,6 +459,23 @@ impl ArtifactStore {
                 {
                     if result.len() == result_limit {
                         report.omitted += 1;
+                        if result_limit > 0 {
+                            return Ok((
+                                report,
+                                result,
+                                TempScanCursor {
+                                    root_dev: root.dev,
+                                    root_ino: root.ino,
+                                    next_shard: shard_number,
+                                    shard_continuation: Some(TempShardContinuation {
+                                        shard: shard_number,
+                                        dev: stat.st_dev,
+                                        ino: stat.st_ino,
+                                        cookie: entry.cookie_before,
+                                    }),
+                                },
+                            ));
+                        }
                         continue;
                     }
                     result.push(StaleTemp {
@@ -385,8 +491,35 @@ impl ArtifactStore {
                     });
                 }
             }
+            if let Some(cookie) = page.continuation {
+                return Ok((
+                    report,
+                    result,
+                    TempScanCursor {
+                        root_dev: root.dev,
+                        root_ino: root.ino,
+                        next_shard: shard_number,
+                        shard_continuation: Some(TempShardContinuation {
+                            shard: shard_number,
+                            dev: stat.st_dev,
+                            ino: stat.st_ino,
+                            cookie,
+                        }),
+                    },
+                ));
+            }
         }
-        Ok((report, result))
+        report.complete = true;
+        Ok((
+            report,
+            result,
+            TempScanCursor {
+                root_dev: root.dev,
+                root_ino: root.ino,
+                next_shard,
+                shard_continuation: None,
+            },
+        ))
     }
 
     /// Deletes a revalidated stale inode under an exclusive lock, then fsyncs.

crates/crank-artifacts/src/lib.rs

@@ -20,7 +20,9 @@ mod temp_scan;
 pub mod test_support;
 
 pub use error::ArtifactError;
-pub use housekeeping::{ReconciliationCandidate, ReconciliationCursor, StaleTemp, TempScan};
+pub use housekeeping::{
+    ReconciliationCandidate, ReconciliationCursor, StaleTemp, TempScan, TempScanCursor,
+};
 pub use model::{
     ArtifactRef, MAX_ARTIFACT_BYTES, MAX_SOURCE_BYTES, ReconciliationMutation,
     ReconciliationNamespace, ReconciliationPresence, ReconciliationRegistration,

crates/crank-artifacts/src/store.rs

@@ -80,6 +80,15 @@ impl ArtifactStore {
         })
     }
 
+    /// Verifies that the pinned root is still the same private directory that
+    /// was accepted at startup. This does not open data by pathname and is
+    /// suitable for a process readiness probe.
+    pub fn check_health(&self) -> Result<(), ArtifactError> {
+        let root = self.root()?;
+        let _lock = RootLock::shared(root)?;
+        ensure_root_unchanged(root)
+    }
+
     /// Compatibility constructor. I/O returns the opening error fail-closed.
     pub fn new(root: impl AsRef<Path>) -> Self {
         Self {

crates/crank-artifacts/src/temp_scan.rs

@@ -1,5 +1,19 @@
 use crate::{ArtifactError, ArtifactStore, TempScan};
 
+pub(crate) struct NamePage {
+    pub(crate) names: Vec<NameEntry>,
+    /// Opaque `telldir` position immediately after the last consumed entry.
+    /// It is meaningful only for the same opened directory inode.
+    pub(crate) continuation: Option<i64>,
+}
+
+pub(crate) struct NameEntry {
+    pub(crate) name: String,
+    /// Directory position immediately before this entry. Resuming here
+    /// guarantees a candidate omitted by a result limit is reconsidered.
+    pub(crate) cookie_before: i64,
+}
+
 pub(crate) fn valid_temp_name(name: &str) -> bool {
     let Some(rest) = name.strip_prefix(ArtifactStore::temp_prefix()) else {
         return false;
@@ -20,11 +34,12 @@ pub(crate) fn valid_temp_name(name: &str) -> bool {
         && sequence.bytes().all(|byte| byte.is_ascii_digit())
 }
 
-pub(crate) fn list_names(
+pub(crate) fn list_names_after(
     parent: i32,
     remaining: &mut usize,
     report: &mut TempScan,
-) -> Result<Vec<String>, ArtifactError> {
+    continuation: Option<i64>,
+) -> Result<NamePage, ArtifactError> {
     let dot = std::ffi::CString::new(".").map_err(|_| ArtifactError::Storage)?;
     let raw = unsafe {
         libc::openat(
@@ -44,13 +59,32 @@ pub(crate) fn list_names(
         return Err(ArtifactError::Storage);
     }
     let mut names = Vec::new();
+    if let Some(cookie) = continuation {
+        unsafe {
+            libc::seekdir(directory, cookie as libc::c_long);
+        }
+    }
     loop {
         if *remaining == 0 {
-            break;
+            let continuation = unsafe { libc::telldir(directory) };
+            unsafe {
+                libc::closedir(directory);
+            }
+            return Ok(NamePage {
+                names,
+                continuation: (continuation >= 0).then_some(continuation as i64),
+            });
         }
         unsafe {
             *libc::__errno_location() = 0;
         }
+        let cookie_before = unsafe { libc::telldir(directory) };
+        if cookie_before < 0 {
+            unsafe {
+                libc::closedir(directory);
+            }
+            return Err(ArtifactError::Storage);
+        }
         let entry = unsafe { libc::readdir(directory) };
         if entry.is_null() {
             if unsafe { *libc::__errno_location() } != 0 {
@@ -59,7 +93,13 @@ pub(crate) fn list_names(
                 }
                 return Err(ArtifactError::Storage);
             }
-            break;
+            unsafe {
+                libc::closedir(directory);
+            }
+            return Ok(NamePage {
+                names,
+                continuation: None,
+            });
         }
         let name = unsafe { std::ffi::CStr::from_ptr((*entry).d_name.as_ptr()) }.to_bytes();
         if name == b"." || name == b".." {
@@ -68,11 +108,10 @@ pub(crate) fn list_names(
         report.scanned += 1;
         *remaining -= 1;
         if let Ok(name) = std::str::from_utf8(name) {
-            names.push(name.to_owned());
+            names.push(NameEntry {
+                name: name.to_owned(),
+                cookie_before: cookie_before as i64,
+            });
         }
     }
-    unsafe {
-        libc::closedir(directory);
-    }
-    Ok(names)
 }