Struct ProjectStateGuard 

pub(crate) struct ProjectStateGuard {
    root: PathBuf,
    root_identity: Handle,
    directory: PathBuf,
    directory_identity: Option<Handle>,
    automatic_database: Option<PathBuf>,
    automatic_document: Option<PathBuf>,
    admission: StateAdmission,
}

Retain the admitted root and existing state-directory objects during writes.

These checks are repeated at mutation boundaries. They do not lock arbitrary ancestors against a hostile concurrent filesystem actor.

Fields

root: PathBuf

Canonical selected source root; source-root aliases are resolved by callers.

root_identity: Handle

Retained root object, preventing reuse of its old filesystem identity.

directory: PathBuf

Admitted publication directory: the root or its direct private directory.

directory_identity: Option<Handle>

Existing state-directory object, when one was present at admission.

automatic_database: Option<PathBuf>

Selected automatic database; external operator paths remain independent.

automatic_document: Option<PathBuf>

Exact automatic document; explicit custom/external paths are not inferred.

admission: StateAdmission

The concrete operation boundary, never a process-global routing setting.

Implementations

impl ProjectStateGuard

pub(crate) fn preflight( root: &Path, database: Option<&Path>, config: Option<&Path>, ) -> Result<Self>

Inspect automatic destinations without creating files or SQLite sidecars.

pub(crate) fn preflight_database_path( database: &Path, selected_root: &Path, ) -> Result<Option<Self>>

Admit an exact managed database before even reading its stored root.

Arbitrary external DB names/locations remain operator-selected, including conventional-looking names under a different root. Resolve only the known selected root; resolving .projectatlas here would trust its alias.

pub(crate) fn preflight_database_reset_path( database: &Path, selected_root: &Path, ) -> Result<Option<Self>>

Admit explicit reset without reading SQLite or refusing recoverable cohorts.

pub(crate) fn preflight_document( root: &Path, path: &Path, ) -> Result<Option<Self>>

Admit one fixed document while preserving custom/external operator paths.

fn admit( root: &Path, database: Option<&Path>, config: Option<&Path>, admission: StateAdmission, ) -> Result<Self>

Capture the exact filesystem owner for one operation role.

pub(crate) fn sqlite_path(&self) -> Option<&Path>

Return the admitted SQLite spelling; Windows managed aliases share one cohort.

pub(crate) fn alternate_reset_paths(&self) -> Result<Vec<PathBuf>>

Enumerate only proven alternate recovery entries for an explicit reset.

pub(crate) fn verify(&self) -> Result<()>

Recheck the admitted objects and every automatic host/database output.

fn verify_directories(&self) -> Result<()>

Check only retained directory objects, including before staging cleanup.

pub(crate) fn ensure_directory(&mut self) -> Result<()>

Create only the admitted direct state directory and retain its object.

pub(crate) fn write_generated(&self, path: &Path, bytes: &[u8]) -> Result<()>

Publish a generated entry without writing through an existing file alias.

pub(crate) fn write_new(&self, path: &Path, bytes: &[u8]) -> Result<()>

Publish defaults without exposing partial bytes or replacing existing data.

pub(crate) fn write_document(&mut self, bytes: &[u8]) -> Result<()>

Replace only the exact admitted document, preserving existing permissions.

pub(crate) fn create_document(&mut self, bytes: &[u8]) -> Result<bool>

Atomically create an admitted document, reporting a racing existing entry.

fn document_path(&self) -> Result<&Path>

Keep document publication bound to its constructor-selected target.

pub(crate) fn owns_entry(&self, path: &Path) -> Result<bool>

Compare actual parent owners while preserving selected path spelling.

fn publish( &self, path: &Path, bytes: &[u8], publication: FilePublication, before_publication: impl FnOnce() -> Result<()>, ) -> Result<bool>

Share atomic publication and a scoped failure boundary across file roles.

fn publish_with_stage_check( &self, path: &Path, bytes: &[u8], publication: FilePublication, stage_check: impl FnOnce(&NamedTempFile) -> Result<()>, before_publication: impl FnOnce() -> Result<()>, ) -> Result<bool>

Observe the real protected stage through a local causal-test seam.

fn verify_staging_file( &self, temporary: &NamedTempFile, directory_identity: &Handle, ) -> Result<()>

Bind path-based metadata, publication and cleanup to the retained file.

fn discard_staging_probe( &self, temporary: NamedTempFile, directory_identity: &Handle, ) -> Result<()>

Retain file authority even when an explicit probe unlink fails.

fn verify_staging_entry( &self, path: &Path, file: &File, directory_identity: &Handle, ) -> Result<()>

Verify a direct stage name against both retained directory and file objects.

fn staging_failure( &self, temporary: &mut NamedTempFile, operation: Error, directory_identity: &Handle, ) -> Error

Never unlink a temporary pathname through a changed directory or file owner.