tensorfs 0.3.77__tar.gz → 0.3.79__tar.gz

{tensorfs-0.3.77 → tensorfs-0.3.79}/Cargo.lock

@@ -439,7 +439,7 @@ checksum = "adb6935a6f5c20170eeceb1a3835a49e12e19d792f6dd344ccc76a985ca5a6ca"
 
 [[package]]
 name = "tensorfs-core"
-version = "0.3.77"
+version = "0.3.79"
 dependencies = [
  "fs2",
  "libc",
@@ -454,7 +454,7 @@ dependencies = [
 
 [[package]]
 name = "tensorfs-py"
-version = "0.3.77"
+version = "0.3.79"
 dependencies = [
  "pyo3",
  "tensorfs-core",

{tensorfs-0.3.77 → tensorfs-0.3.79}/Cargo.toml

@@ -3,5 +3,5 @@ resolver = "2"
 members = ["crates/tensorfs-core", "crates/tensorfs-py"]
 
 [workspace.package]
-version = "0.3.77"
+version = "0.3.79"
 edition = "2021"

{tensorfs-0.3.77 → tensorfs-0.3.79}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tensorfs
-Version: 0.3.77
+Version: 0.3.79
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Programming Language :: Rust

tensorfs-0.3.79/crates/tensorfs-core/src/bin/tfs/ensure.rs

@@ -0,0 +1,160 @@
+//! `tfs ensure <root> <ref> --hub <base>`: make one model resident (proto-063 M2a).
+//!
+//! STDOUT is JSON lines and nothing else: `ensure.progress` samples, then exactly one
+//! `ensure.result` (exit 0) or `ensure.refused` (exit 1). Usage errors exit 2.
+
+use std::io::Write;
+use std::path::Path;
+use std::process::ExitCode;
+use std::sync::Mutex;
+
+use tensorfs_core::canon::{self, Value};
+use tensorfs_core::ensure::{self, Ensured, Event, Request};
+use tensorfs_core::err::Refusal;
+use tensorfs_core::store::Store;
+use tensorfs_core::transport;
+
+use crate::{flag, flag_all, flag_num, Flags};
+
+fn read(path: &str) -> Result<Vec<u8>, Refusal> {
+    std::fs::read(path).map_err(|e| Refusal {
+        code: tensorfs_core::err::Code::IO_FAILED,
+        detail: format!("read {path}: {e}"),
+    })
+}
+
+fn quoted(text: &str) -> String {
+    String::from_utf8(canon::write(&Value::str(text))).unwrap()
+}
+
+fn say(out: &Mutex<std::io::Stdout>, line: String) {
+    let mut out = out.lock().unwrap();
+    // A closed reader is not this download's business; the bytes are still wanted.
+    let _ = writeln!(out, "{line}").and_then(|()| out.flush());
+}
+
+fn progress(event: &Event) -> String {
+    format!(
+        "{{\"event\":\"ensure.progress\",\"model\":{},\"step\":{},\"phase\":\"{}\",\"bytes_done\":{},\"bytes_total\":{},\"rate\":{:.1},\"attempt\":{}}}",
+        quoted(&event.model),
+        quoted(&event.step),
+        event.phase.as_str(),
+        event.bytes_done,
+        event.bytes_total,
+        event.rate,
+        event.attempt,
+    )
+}
+
+fn result(r: &Ensured) -> String {
+    format!(
+        "{{\"event\":\"ensure.result\",\"model\":{},\"release\":{},\"lane\":{},\"scope\":{},\"manifest\":\"{}\",\"manifest_length\":{},\"bytes_total\":{},\"bytes_held\":{},\"bytes_fetched\":{},\"bytes_cached\":{},\"cache_written_bytes\":{},\"collected_bytes\":{},\"attempts\":{},\"joined\":{},\"seconds\":{:.3}}}",
+        quoted(&r.model),
+        quoted(&r.release),
+        quoted(&r.lane),
+        quoted(&r.scope),
+        r.manifest.id(),
+        r.manifest.length,
+        r.bytes_total,
+        r.bytes_held,
+        r.bytes_fetched,
+        r.bytes_cached,
+        r.cache_written_bytes,
+        r.collected_bytes,
+        r.attempts,
+        r.joined,
+        r.seconds,
+    )
+}
+
+fn refused(refusal: &Refusal, model: &str, step: &str) -> String {
+    format!(
+        "{{\"event\":\"ensure.refused\",\"code\":\"{}\",\"resumable\":{},\"detail\":{},\"model\":{},\"step\":{}}}",
+        refusal.code.as_str(),
+        ensure::resumable(refusal.code),
+        quoted(&refusal.detail),
+        quoted(model),
+        quoted(step),
+    )
+}
+
+pub fn cmd_ensure(root: &Path, refspec: &str, flags: &Flags) -> ExitCode {
+    let Some(hub) = flag(flags, "hub") else {
+        eprintln!("--hub <base-url> is required");
+        return ExitCode::from(2);
+    };
+    let out = Mutex::new(std::io::stdout());
+    let model = refspec.split('@').next().unwrap_or_default();
+    let step = flag(flags, "step").unwrap_or("");
+    let answer = |outcome: Result<Ensured, Refusal>| match outcome {
+        Ok(ensured) => {
+            say(&out, result(&ensured));
+            ExitCode::SUCCESS
+        }
+        Err(refusal) => {
+            say(&out, refused(&refusal, model, step));
+            ExitCode::FAILURE
+        }
+    };
+    let setup = || -> Result<_, Refusal> {
+        if let Some(path) = flag(flags, "ca-file") {
+            transport::trust_roots(&read(path)?)?;
+        }
+        // The credential reaches the child as a file or TFS_CREDENTIAL, never argv.
+        let spec = match flag(flags, "credential-file") {
+            Some(path) => String::from_utf8_lossy(&read(path)?).into_owned(),
+            None => std::env::var("TFS_CREDENTIAL").unwrap_or_default(),
+        };
+        let credential =
+            transport::credential_from_spec(spec.trim(), vec![transport::base_host(hub)?])?;
+        Ok((Store::open(root)?, credential))
+    };
+    let (store, credential) = match setup() {
+        Ok(setup) => setup,
+        Err(refusal) => return answer(Err(refusal)),
+    };
+    let policy = crate::fetch::policy_of(flags);
+    let keep: Vec<String> = flag_all(flags, "keep")
+        .into_iter()
+        .map(str::to_string)
+        .collect();
+    let on_event = |event: &Event| say(&out, progress(event));
+    let mut request = Request::new(&store, hub, refspec, &credential, &policy);
+    request.lane = flag(flags, "lane").unwrap_or("");
+    request.step = step;
+    request.keep = &keep;
+    request.streams = flag_num(flags, "streams", transport::PULL_STREAMS);
+    request.streams_start = flag_num(flags, "streams-start", transport::STREAMS);
+    request.sample_seconds = flag_num(flags, "sample-seconds", transport::SAMPLE_SECONDS);
+    request.on_event = Some(&on_event);
+    answer(ensure::ensure(&request))
+}
+
+/// `tfs pressure <root> [--keep sha256:<m>]...`: one pressure pass (see `ensure::relieve`),
+/// reported as one JSON line.
+pub fn cmd_pressure(root: &Path, flags: &Flags) -> ExitCode {
+    let keep: Vec<String> = flag_all(flags, "keep")
+        .into_iter()
+        .map(str::to_string)
+        .collect();
+    let relief = match Store::open(root).and_then(|store| ensure::relieve(&store, &keep)) {
+        Ok(relief) => relief,
+        Err(refusal) => {
+            println!(
+                "{{\"event\":\"pressure.refused\",\"code\":\"{}\",\"detail\":{}}}",
+                refusal.code.as_str(),
+                quoted(&refusal.detail)
+            );
+            return ExitCode::FAILURE;
+        }
+    };
+    println!(
+        "{{\"event\":\"pressure\",\"pressure\":{},\"collected_bytes\":{},\"capacity_bytes\":{},\"available_bytes\":{},\"unable\":{}}}",
+        relief.pressure,
+        relief.collected_bytes,
+        relief.capacity_bytes,
+        relief.available_bytes,
+        relief.unable.as_deref().map_or("null".to_string(), quoted),
+    );
+    ExitCode::SUCCESS
+}

{tensorfs-0.3.77 → tensorfs-0.3.79}/crates/tensorfs-core/src/bin/tfs/fetch.rs

@@ -168,7 +168,7 @@ use tensorfs_core::transport::{
     self, credential_from_spec, Anonymous, Deadline, PullRequest, SourcePolicy,
 };
 
-fn policy_of(flags: &Flags) -> SourcePolicy {
+pub(crate) fn policy_of(flags: &Flags) -> SourcePolicy {
     SourcePolicy {
         allowed_hosts: crate::flag(flags, "allow-hosts")
             .map(|hosts| {

{tensorfs-0.3.77 → tensorfs-0.3.79}/crates/tensorfs-core/src/bin/tfs/ingest.rs

@@ -574,6 +574,7 @@ pub fn cmd_bank(dialect: &str, converter: &str, f: &Flags) -> ExitCode {
             return ExitCode::FAILURE;
         }
         let profile = SourceProfile {
+            auto_select: true,
             name: name.to_string(),
             components,
         };

{tensorfs-0.3.77 → tensorfs-0.3.79}/crates/tensorfs-core/src/bin/tfs/main.rs

@@ -31,7 +31,8 @@
 //!                                   [--session <s>] [--tenant <t>] [--no-journal]
 //!   tfs repo-cache chain <cache> <chain-id> <length>       the links, root to head
 //!   tfs put <root> <file>        stream one object in (any shape)
-//!   tfs get <root> <hex>         verified read, whole or ranged
+//!   tfs get <root> <hex>         verified read, whole or ranged; with --out - the bytes
+//!                                go to stdout under a read lease (--range <off>:<len>|<off>:)
 //!   tfs contains <root> <hex>    the presence HINT, and what it is worth
 //!   tfs verify <root> <hex>      verification record or rehash; remove corrupt bytes
 //!   tfs scrub <root>             one rate knob over the whole store
@@ -48,6 +49,15 @@
 //! `tfs fetch` reads and backfills the Store's bound repo cache between the local Store
 //! and the origin. It is bound by `tfs store ensure --repo-cache` and never by a flag here.
 //!
+//!   tfs capabilities             one feature name per line (ensure/1, get-range/1, ...)
+//!   tfs ensure <root> <ref> --hub <base> [--lane L] [--step S] [--keep sha256:<m>]...
+//!                               make one model resident: closure, one flight per manifest per
+//!                               Store, disk admission + GC policy, paced resumable fetch, retry
+//!                               only after measured progress. STDOUT is JSON lines:
+//!                               ensure.progress samples, then ensure.result (exit 0) or
+//!                               ensure.refused {code, resumable, detail} (exit 1)
+//!   tfs pressure <root> [--keep sha256:<m>]...   one pressure pass: at <= 1/10 free, run
+//!                               the GC policy until > 1/5 is free; one JSON line
 //!   tfs fetch <root> <ref>       closure -> plan -> N-way walk (presign at use) -> proof
 //!   tfs fetch bounded <root> <ref> --max-download-bytes N --max-download-objects N
 //!                               same pull, refused before body transfer if new objects exceed bounds
@@ -203,7 +213,9 @@ fn accept_printed_ids(args: Vec<String>) -> Vec<String> {
 
 fn main() -> ExitCode {
     let (args, flags) = split_flags(std::env::args().skip(1).collect());
-    if let Some(path) = flag(&flags, "ca-file") {
+    // `ensure` names its CA itself so a bad file is a refusal on its own channel.
+    let ensure = args.first().is_some_and(|verb| verb == "ensure");
+    if let (Some(path), false) = (flag(&flags, "ca-file"), ensure) {
         let trusted = fs::read(path)
             .map_err(|e| format!("IO_FAILED: read {path}: {e}"))
             .and_then(|pem| {
@@ -218,6 +230,14 @@ fn main() -> ExitCode {
     let a: Vec<&str> = args.iter().map(|s| s.as_str()).collect();
     match a.as_slice() {
         ["version"] => cmd_version(),
+        ["capabilities"] => {
+            tensorfs_core::CAPABILITIES
+                .iter()
+                .for_each(|c| println!("{c}"));
+            ExitCode::SUCCESS
+        }
+        ["ensure", r, refspec] => ensure::cmd_ensure(Path::new(r), refspec, &flags),
+        ["pressure", r] => ensure::cmd_pressure(Path::new(r), &flags),
         ["home"] => cmd_home(None),
         ["home", r] => cmd_home(Some(Path::new(r))),
         ["store", "init"] => cmd_store_default("init", &flags),
@@ -815,6 +835,7 @@ macro_rules! ok {
 
 mod ckpt;
 mod conform;
+mod ensure;
 mod fetch;
 mod ingest;
 mod rd;
@@ -936,6 +957,67 @@ fn fault_of(f: &Flags) -> Fault {
     }
 }
 
+/// `<off>:<len>` or `<off>:` (to the end) inside an object of `length` bytes.
+fn byte_range(range: &str, length: u64) -> TfsResult<(u64, u64)> {
+    let bad = || Refusal {
+        code: tensorfs_core::err::Code::RANGE_BOUNDS,
+        detail: format!("--range {range:?} is not <off>:<len> or <off>: inside {length} B"),
+    };
+    let (off, len) = range.split_once(':').ok_or_else(bad)?;
+    let off: u64 = off.parse().map_err(|_| bad())?;
+    let len: u64 = match len {
+        "" => length.checked_sub(off).ok_or_else(bad)?,
+        len => len.parse().map_err(|_| bad())?,
+    };
+    match off.checked_add(len) {
+        Some(end) if end <= length => Ok((off, len)),
+        _ => Err(bad()),
+    }
+}
+
+/// Stream a range of one verified object to stdout under a read lease, so a GC pass cannot
+/// take the object mid-read.
+fn get_leased(store: &Store, hex: &str, range: Option<&str>) -> TfsResult<()> {
+    use std::io::Write;
+    use tensorfs_core::read::{self, ObjectRange};
+    let length = store.open_verified(hex)?.len();
+    let (mut off, mut left) = match range {
+        Some(range) => byte_range(range, length)?,
+        None => (0, length),
+    };
+    let meta = tensorfs_core::meta::Meta::open(store)?;
+    let obj = ObjectRef {
+        sha256: hex.to_string(),
+        length,
+    };
+    let (lease, _) = read::acquire(store, &meta, "", vec![obj.clone()])?;
+    let mut out = std::io::stdout().lock();
+    let mut buf = vec![0u8; 1 << 20];
+    let streamed = (|| {
+        while left > 0 {
+            let n = left.min(buf.len() as u64);
+            let chunk = &mut buf[..n as usize];
+            let range = ObjectRange {
+                obj: obj.clone(),
+                off,
+                len: n,
+            };
+            read::read_into(&lease, &range, chunk)?;
+            out.write_all(chunk).map_err(|e| Refusal {
+                code: tensorfs_core::err::Code::IO_FAILED,
+                detail: format!("write stdout: {e}"),
+            })?;
+            (off, left) = (off + n, left - n);
+        }
+        out.flush().map_err(|e| Refusal {
+            code: tensorfs_core::err::Code::IO_FAILED,
+            detail: format!("write stdout: {e}"),
+        })
+    })();
+    lease.release(&meta)?;
+    streamed
+}
+
 fn cmd_put(root: &Path, src: &Path, f: &Flags) -> ExitCode {
     let s = ok!(Store::open(root));
     let expect = match (flag(f, "expect"), flag(f, "expect-length")) {
@@ -1016,6 +1098,10 @@ fn cmd_verify_object(root: &Path, hex: &str, f: &Flags) -> ExitCode {
 
 fn cmd_get(root: &Path, hex: &str, f: &Flags) -> ExitCode {
     let s = ok!(Store::open(root));
+    if flag(f, "out") == Some("-") {
+        ok!(get_leased(&s, hex, flag(f, "range")));
+        return ExitCode::SUCCESS;
+    }
     let t = Instant::now();
     if let Some(r) = flag(f, "range") {
         let (o, l) = r.split_once(':').unwrap_or((r, "1"));

tensorfs-0.3.79/crates/tensorfs-core/src/catalog/lock.rs

@@ -0,0 +1,206 @@
+//! Waiting for another process's catalog lock by whether its holder can still release it.
+//!
+//! SQLite's locks are POSIX locks: they die with the process that holds them. A holder
+//! that is alive is committing or about to, so a writer waits for it for as long as it
+//! takes; a flat deadline refused a busy, progressing writer as if it were dead. The only
+//! holder that cannot release is one that is stopped (a debugger or SIGSTOP), and only
+//! then does a statement give up. Dead processes have already released their locks.
+//!
+//! Holders come from `/proc/locks`, matched by the catalog's inode (and its WAL `-shm`).
+//! The catalog file itself is never opened here: closing a second descriptor on it would
+//! drop every POSIX lock this process holds on it.
+
+use std::cell::RefCell;
+use std::path::{Path, PathBuf};
+use std::time::Duration;
+
+use rusqlite::Connection;
+
+use crate::err::Result;
+
+thread_local! {
+    /// The catalog this thread's statements wait on. A connection is opened for each
+    /// operation just before it is used, on the thread that uses it, so the one opened last
+    /// here is the one a busy statement belongs to.
+    static WAITING_ON: RefCell<Option<PathBuf>> = const { RefCell::new(None) };
+}
+
+/// Install the waiting handler on one connection.
+pub(crate) fn wait_for_live_holders(connection: &Connection, path: &Path) -> Result<()> {
+    WAITING_ON.with(|waiting| *waiting.borrow_mut() = Some(path.to_path_buf()));
+    connection
+        .busy_handler(Some(busy))
+        .map_err(|error| super::sql("install catalog lock wait", error))
+}
+
+fn busy(attempt: i32) -> bool {
+    let path = WAITING_ON.with(|waiting| waiting.borrow().clone());
+    if path.is_some_and(|path| holders_cannot_release(&path)) {
+        return false;
+    }
+    std::thread::sleep(Duration::from_millis(attempt.clamp(1, 64) as u64));
+    true
+}
+
+/// Every currently held write lock belongs to a stopped process. Without a current
+/// holder to name (the lock just went, or no `/proc`), keep asking.
+fn holders_cannot_release(path: &Path) -> bool {
+    let files: Vec<(u64, u64)> = [path.to_path_buf(), shm(path)]
+        .iter()
+        .filter_map(|file| std::fs::metadata(file).ok())
+        .map(|metadata| {
+            use std::os::unix::fs::MetadataExt;
+            (metadata.dev(), metadata.ino())
+        })
+        .collect();
+    let Ok(locks) = std::fs::read_to_string("/proc/locks") else {
+        return false;
+    };
+    snapshots_cannot_release(&locks, &files, std::process::id(), stopped, || {
+        std::fs::read_to_string("/proc/locks").ok()
+    })
+}
+
+fn snapshots_cannot_release(
+    observed: &str,
+    files: &[(u64, u64)],
+    own: u32,
+    is_stopped: impl Fn(u32) -> bool,
+    current: impl FnOnce() -> Option<String>,
+) -> bool {
+    let holders = write_holders(observed, files, own);
+    if holders.is_empty() || !holders.iter().all(|pid| is_stopped(*pid)) {
+        return false;
+    }
+    // A holder may unlock or exit between the lock snapshot and its process-state
+    // read. Refuse only if those stopped processes still hold the actual locks.
+    let Some(current) = current() else {
+        return false;
+    };
+    let current = write_holders(&current, files, own);
+    !current.is_empty()
+        && current
+            .iter()
+            .all(|pid| holders.contains(pid) && is_stopped(*pid))
+}
+
+fn shm(path: &Path) -> PathBuf {
+    let mut name = path.as_os_str().to_owned();
+    name.push("-shm");
+    PathBuf::from(name)
+}
+
+/// Other processes' POSIX write locks on these inodes, from `/proc/locks` lines such as
+/// `3: POSIX  ADVISORY  WRITE 167671 103:02:204736108 1073741824 1073742335`.
+fn write_holders(locks: &str, files: &[(u64, u64)], own: u32) -> Vec<u32> {
+    locks
+        .lines()
+        .filter_map(|line| {
+            let fields: Vec<&str> = line.split_whitespace().collect();
+            let at = fields.iter().position(|field| *field == "POSIX")?;
+            if fields[..at].contains(&"->") || fields.get(at + 2) != Some(&"WRITE") {
+                return None;
+            }
+            let pid: u32 = fields.get(at + 3)?.parse().ok()?;
+            let mut file = fields.get(at + 4)?.split(':');
+            let major = u32::from_str_radix(file.next()?, 16).ok()?;
+            let minor = u32::from_str_radix(file.next()?, 16).ok()?;
+            let inode: u64 = file.next()?.parse().ok()?;
+            let device = rustix::fs::makedev(major, minor) as u64;
+            (file.next().is_none() && pid != own && files.contains(&(device, inode))).then_some(pid)
+        })
+        .collect()
+}
+
+/// Only stopped and traced-stopped processes keep locks they cannot release.
+fn stopped(pid: u32) -> bool {
+    std::fs::read_to_string(format!("/proc/{pid}/stat"))
+        .ok()
+        .is_some_and(|stat| process_is_stopped(&stat))
+}
+
+fn process_is_stopped(stat: &str) -> bool {
+    stat.rsplit_once(')')
+        .and_then(|(_, fields)| fields.split_whitespace().next())
+        .is_some_and(|state| matches!(state, "T" | "t"))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn only_other_processes_write_locks_on_the_catalog_are_holders() {
+        let locks = "\
+1: POSIX  ADVISORY  WRITE 4242 103:02:77 1073741824 1073742335
+2: POSIX  ADVISORY  READ  5151 103:02:77 1073741826 1073742335
+3: POSIX  ADVISORY  WRITE 6161 103:02:99 120 120
+4: FLOCK  ADVISORY  WRITE 7171 103:02:77 0 EOF
+5: POSIX  ADVISORY  WRITE 1000 103:02:77 0 EOF
+6: -> POSIX  ADVISORY  WRITE 8181 103:02:77 0 EOF
+7: POSIX  ADVISORY  WRITE 9191 104:02:77 0 EOF
+";
+        let device = rustix::fs::makedev(0x103, 2) as u64;
+        assert_eq!(write_holders(locks, &[(device, 77)], 1000), vec![4242]);
+        assert_eq!(
+            write_holders(locks, &[(device, 77), (device, 99)], 1000),
+            vec![4242, 6161]
+        );
+        assert!(write_holders(locks, &[(device, 5)], 1000).is_empty());
+    }
+
+    #[test]
+    fn exited_holder_is_progress_and_never_a_stopped_writer() {
+        for state in ["Z", "X", "R", "S", "D"] {
+            assert!(!process_is_stopped(&format!("4242 (writer) {state} 1 2 3")));
+        }
+        for state in ["T", "t"] {
+            assert!(process_is_stopped(&format!("4242 (writer) {state} 1 2 3")));
+        }
+        assert!(!process_is_stopped("unavailable"));
+    }
+
+    #[test]
+    fn stopped_holder_must_still_own_the_lock_before_refusal() {
+        let held = "1: POSIX ADVISORY WRITE 4242 103:02:77 0 EOF\n";
+        let files = [(rustix::fs::makedev(0x103, 2) as u64, 77)];
+        // Stable SIGSTOP remains a typed refusal, while snapshot -> unlock ->
+        // SIGSTOP must let SQLite retry rather than refuse the old snapshot.
+        assert!(snapshots_cannot_release(
+            held,
+            &files,
+            1000,
+            |_| true,
+            || Some(held.into())
+        ));
+        assert!(!snapshots_cannot_release(
+            held,
+            &files,
+            1000,
+            |_| true,
+            || Some(String::new())
+        ));
+        assert!(!snapshots_cannot_release(
+            held,
+            &files,
+            1000,
+            |_| true,
+            || None
+        ));
+        let replacement = held.replace("4242", "6161");
+        assert!(!snapshots_cannot_release(
+            held,
+            &files,
+            1000,
+            |_| true,
+            || Some(replacement)
+        ));
+        assert!(!snapshots_cannot_release(
+            held,
+            &files,
+            1000,
+            |_| false,
+            || panic!("a live holder must retry")
+        ));
+    }
+}

{tensorfs-0.3.77 → tensorfs-0.3.79}/crates/tensorfs-core/src/catalog.rs

@@ -104,7 +104,14 @@ pub fn connections_opened(root: &Path) -> u64 {
         .unwrap_or(0)
 }
 
-fn connect(path: &Path) -> Result<Connection> {
+pub(crate) fn connect(path: &Path) -> Result<Connection> {
+    // SQLite creates WAL/SHM files before assigning their database owner. Opening
+    // them under root exposes a transient root-owned inode to concurrent owner
+    // connections, which can permanently fall back to read-only WAL access.
+    let _identity = crate::filesystem_identity::FilesystemIdentity::for_store_root(
+        path.parent().unwrap_or(path),
+    )
+    .map_err(|error| io("enter catalog filesystem identity", error))?;
     *opened()
         .lock()
         .unwrap_or_else(|error| error.into_inner())
@@ -253,6 +260,26 @@ impl Trust {
         self.load(&mut kept).map(|_| ())
     }
 
+    /// Finish setup on the already-validated reader connection. The callback is
+    /// synchronous under its mutex; no second setup connection or credential
+    /// lifetime escapes into the returned value.
+    pub(crate) fn with_connection<T>(
+        &self,
+        use_connection: impl FnOnce(&mut Connection) -> Result<T>,
+    ) -> Result<T> {
+        let mut kept = self.kept.lock().unwrap_or_else(|error| error.into_inner());
+        self.load(&mut kept)?;
+        let connection = &mut kept.as_mut().expect("validated connection").connection;
+        // A kept connection can be used by another Runtime thread later. Install
+        // the lock context on the thread actually executing this operation.
+        lock::wait_for_live_holders(connection, &self.path)?;
+        let _identity = crate::filesystem_identity::FilesystemIdentity::for_store_root(
+            self.path.parent().unwrap_or(&self.path),
+        )
+        .map_err(|error| io("enter catalog filesystem identity", error))?;
+        use_connection(connection)
+    }
+
     fn miss(&self, sha256: &str) -> Option<crate::store::VRecord> {
         let mut kept = self.kept.lock().unwrap_or_else(|error| error.into_inner());
         if self.load(&mut kept).ok()? {