pf_world/lib.rs
1// SPDX-License-Identifier: MIT
2//! # `pf-world`
3//!
4//! Captures and restores the world a sandboxed agent inhabits: the
5//! filesystem, environment variables, in-flight subprocess state (Linux
6//! only via CRIU), and — eventually — an attached browser DOM via CDP.
7//!
8//! See `agent_docs/world-layer.md` for the spec.
9//!
10//! ## What ships in Phase 2 (this commit)
11//!
12//! - [`WalkFsCapture`]: portable rayon-parallel file walker that
13//! content-addresses every file into a [`pf_core::cas::BlobStore`] and
14//! emits a tree manifest. Restorable via [`restore_tree`].
15//! - [`EnvCapture`]: serializes `std::env::vars()` + cwd, with
16//! `--scrub-env <regex>` redaction.
17//! - [`ProcsCapture`]: CRIU dump on Linux (shellout); on every other host a
18//! self-describing JSON placeholder per `agent_docs/world-layer.md`.
19//!
20//! ## What's planned but stubbed
21//!
22//! - macOS APFS clone fast-path via `clonefile(2)`: when the source dir
23//! sits on APFS, `WalkFsCapture::with_apfs_clone` first clones the dir
24//! in O(1), then walks the clone — giving a stable read-snapshot without
25//! pausing the agent. Wired but not enabled by default; see
26//! [`WalkFsCapture::use_apfs_clone`].
27//! - Linux overlayfs upper-dir capture: deferred to v1.1 (documented in
28//! the v2 list of `claude-progress.json`).
29
30// `forbid(unsafe_code)` is too strict because `std::env::set_var` is unsafe
31// since Rust 1.85 — we need it in the env-capture tests. We use `deny`
32// (overridable) at the crate level and locally allow only in the test
33// modules that touch process-global env state.
34#![deny(unsafe_code)]
35#![allow(missing_docs)] // docs added per-symbol in submodules
36
37pub mod browser;
38pub mod env;
39pub mod fs;
40pub mod procs;
41
42pub use browser::{BrowserBlob, BrowserCapture, PageSnapshot};
43pub use env::EnvCapture;
44pub use fs::{
45 FsEntryKind, FsTree, FsTreeEntry, RestoreOptions, WalkFsCapture, restore_tree,
46 restore_tree_with_options,
47};
48pub use procs::ProcsCapture;