Struct Checkout 

pub struct Checkout<A, O> { /* private fields */ }

Immutable generation-fenced checkout admitted by the embedded facade.

Implementations

impl<A, O> Checkout<A, O>

pub const fn volume_id(&self) -> VolumeId

Owning volume identity.

pub const fn volume_config(&self) -> VolumeConfig

Immutable owning-volume semantics and operation bounds.

pub const fn generation_id(&self) -> GenerationId

Exact immutable generation identity.

pub const fn root(&self) -> &GenerationRoot

Authenticated decoded generation root.

pub const fn mode(&self) -> CheckoutMode

Admitted checkout behavior.

pub fn has_pending_mutations(&self) -> bool

Whether the private candidate differs from its immutable base.

pub fn snapshot_reader(&self) -> PinnedReader<A, O>

Creates an immutable reader for this checkout’s current private candidate.

The reader snapshots the exact authenticated root already held by the checkout, including pending private overlay state, without authority or storage work. Later checkout mutations do not change the snapshot.

pub fn pinned_reader(&self) -> Result<PinnedReader<A, O>, FsError>

Creates an immutable reader for a pinned checkout.

Errors

Rejects non-pinned checkouts before any storage work.

pub fn content_stager(&self) -> ContentStager<A, O>

Creates an immutable content writer that can stage independent sources concurrently before this checkout admits their ordered mutations.

impl<A: AsyncAuthorityStore, O: AsyncObjectStore> Checkout<A, O>

pub async fn prepare_merge( &mut self, theirs: GenerationId, maximum_changes: u32, maximum_conflicts: u32, budget: WorkBudget, cancellation: &CancellationToken, ) -> FsResult<MergePreparation>

Prepares one bounded two-parent merge against this checkout’s immutable base.

Independent file identities merge without scanning equal Merkle subtrees. A conflict leaves the checkout unchanged; a successful result is an authenticated unpublished generation that must be committed or discarded.

Errors

Rejects non-writable/prepared checkouts, foreign generations, truncated change frontiers, malformed storage, cancellation, or bounded-work failure.

pub async fn export_manifest( &self, budget: WorkBudget, cancellation: &CancellationToken, ) -> FsResult<GenerationExportManifest>

Builds a deterministic complete manifest for the current immutable or sparse candidate generation without publishing authority.

A dirty checkout first writes one unreachable checkpoint root; the complete closure is then authenticated and sorted. Object bodies remain independently transferable through Fs::export_object.

Errors

Returns typed checkpoint, closure, cancellation, storage, allocation, authentication, or bounded-work failures.

pub async fn checkpoint( &self, budget: WorkBudget, cancellation: &CancellationToken, ) -> FsResult<GenerationId>

Writes the immutable generation-root checkpoint for the current sparse candidate without publishing authority.

A clean checkout returns its selected generation with zero object work. Repeated dirty checkpoints are content-addressed and therefore exactly idempotent. The checkout and its pending publication state are unchanged.

Errors

Returns typed canonical encoding, storage, cancellation, allocation, or bounded-work failures.

pub async fn discard( &mut self, budget: WorkBudget, cancellation: &CancellationToken, ) -> FsResult<()>

Discards a private candidate and reauthenticates its immutable base.

Errors

Rejects non-overlay modes and returns exact cancellation, storage, decode, or budget failures without changing the checkout on failure.

pub async fn refresh_head( &mut self, budget: WorkBudget, cancellation: &CancellationToken, ) -> FsResult<GenerationId>

Explicitly advances one clean manual or tracking checkout to head.

Equal generations avoid an immutable-object read. Dirty overlays are retained and rejected because adopting them requires safe rebase.

Errors

Rejects pinned, live, or dirty checkouts and returns exact authority, storage, authentication, cancellation, or budget failures.

pub async fn rebase_head( &mut self, maximum_conflicts: u32, budget: WorkBudget, cancellation: &CancellationToken, ) -> FsResult<RebaseDecision>

Safely advances to the current head and rebases the private candidate.

Only exact regions captured by reads and mutation preconditions are compared. A conflict leaves the checkout unchanged. A safe dirty rebase combines the immutable candidate with the new base without retaining an unbounded operation log.

Errors

Returns measured authority, probe, decode, replay, cancellation, or budget failures without changing the checkout unless the full rebase succeeds.

pub async fn refresh_live( &mut self, budget: WorkBudget, cancellation: &CancellationToken, ) -> FsResult<GenerationId>

Explicitly performs the same observation-safe head advancement used automatically before live reads.

Errors

Rejects non-live checkouts and returns a typed region conflict rather than crossing any prior observation or pending mutation dependency.

pub async fn mutate( &mut self, operations: Vec<Mutation>, budget: WorkBudget, cancellation: &CancellationToken, ) -> FsResult<()>

Atomically applies one ordered mutation batch to this private checkout.

The immutable base remains unchanged. A failed batch may leave harmless unreferenced objects but never replaces the checkout candidate.

Errors

Rejects non-writable modes and returns exact planning, storage, cancellation, semantic, or work-budget failures.

pub async fn mutate_live( &mut self, operations: Vec<Mutation>, operation_id: OperationId, maximum_attempts: u32, maximum_conflicts: u32, budget: WorkBudget, cancellation: &CancellationToken, ) -> FsResult<LiveMutationOutcome>

Applies and durably publishes one direct-live mutation operation.

Authority races are automatically rebased only when every exact read and mutation dependency remains unchanged. The stable operation ID is reused across those safe retries. A region conflict or exhausted retry bound leaves the sparse candidate available to Self::resume_live or Self::discard.

Errors

Rejects non-live modes, an existing unresolved candidate, zero bounds, and returns exact mutation, rebase, publication, cancellation, storage, or work-budget failures.

pub async fn apply_authored_live( &mut self, authored: Vec<AuthoredMutation>, operation_id: OperationId, maximum_attempts: u32, maximum_conflicts: u32, budget: WorkBudget, cancellation: &CancellationToken, ) -> FsResult<AuthoredLiveMutationResult>

Compiles, atomically applies, and durably publishes one authored live transaction.

This is the canonical byte-oriented direct-live orchestration boundary for language SDKs. It preserves generated file identities and one exact work receipt across content staging, sparse mutation, safe rebase, and authority publication.

Errors

Returns the combined failures of Self::apply_authored_transaction and Self::resume_live. An unresolved publication retains the sparse candidate for an exact Self::resume_live retry.

pub async fn resume_live( &mut self, operation_id: OperationId, maximum_attempts: u32, maximum_conflicts: u32, budget: WorkBudget, cancellation: &CancellationToken, ) -> FsResult<LiveMutationOutcome>

Resumes publication of an unresolved direct-live candidate.

The caller must reuse the original operation ID after an indeterminate transport result. Exact authority idempotency resolves whether that operation was already durable.

Errors

Returns the same failures as Self::mutate_live and rejects a clean checkout.

pub async fn apply_authored_transaction( &mut self, authored: Vec<AuthoredMutation>, budget: WorkBudget, cancellation: &CancellationToken, ) -> FsResult<AuthoredTransactionResult>

Compiles and atomically applies one complete caller-authored transaction.

Immutable byte and metadata objects are admitted before the candidate root is replaced. Failure may leave unreachable immutable objects, but never a partially changed checkout candidate.

Errors

Rejects excessive input, unsupported kinds, invalid ranges, non-writable checkouts, semantic conflicts, cancellation, storage failures, or work beyond the caller’s exact budget.

pub async fn create_file( &mut self, path: NamespacePath, bytes: Bytes, budget: WorkBudget, cancellation: &CancellationToken, ) -> FsResult<FileId>

Creates a regular file, embedding tiny content and sparsely staging larger content in one atomic checkout mutation batch.

Errors

Returns measured path, identity, encoding, blob, mutation, storage, cancellation, allocation, or bounded-work failures.

pub async fn create_directory( &mut self, path: NamespacePath, budget: WorkBudget, cancellation: &CancellationToken, ) -> FsResult<FileId>

Creates an empty directory without scanning its parent or siblings.

Errors

Returns measured path, encoding, mutation, storage, cancellation, allocation, or bounded-work failures.

pub async fn create_symbolic_link( &mut self, path: NamespacePath, target: Bytes, budget: WorkBudget, cancellation: &CancellationToken, ) -> FsResult<FileId>

Creates a symbolic link whose target bytes remain opaque and exact.

Errors

Returns typed capability, path, blob, metadata, mutation, storage, cancellation, allocation, or bounded-work failures.

pub async fn read_symbolic_link( &mut self, path: &NamespacePath, budget: WorkBudget, cancellation: &CancellationToken, ) -> FsResult<Bytes>

Reads exact opaque symbolic-link target bytes without following it.

Errors

Returns typed absence, kind, corruption, cancellation, storage, allocation, or bounded-work failures.

pub async fn create_empty_special( &mut self, path: NamespacePath, kind: FileKind, budget: WorkBudget, cancellation: &CancellationToken, ) -> FsResult<FileId>

Creates a FIFO, socket, or explicit mounted-volume boundary.

Errors

Rejects payload-bearing kinds and returns typed metadata, mutation, storage, cancellation, or bounded-work failures.

pub async fn create_device( &mut self, path: NamespacePath, kind: FileKind, major: u32, minor: u32, budget: WorkBudget, cancellation: &CancellationToken, ) -> FsResult<FileId>

Creates an exact POSIX character or block device identity.

Errors

Rejects non-device kinds and returns typed metadata, mutation, storage, cancellation, or bounded-work failures.

pub async fn create_reparse_point( &mut self, path: NamespacePath, payload: Bytes, budget: WorkBudget, cancellation: &CancellationToken, ) -> FsResult<FileId>

Creates an opaque Windows reparse-point payload.

Errors

Returns typed path, blob, metadata, mutation, storage, cancellation, allocation, or bounded-work failures.

pub async fn read_reparse_point( &mut self, path: &NamespacePath, budget: WorkBudget, cancellation: &CancellationToken, ) -> FsResult<Bytes>

Reads exact opaque Windows reparse-point bytes without interpreting them.

Errors

Returns typed absence, kind, corruption, cancellation, storage, allocation, or bounded-work failures.

pub async fn write_file( &mut self, path: NamespacePath, offset: u64, bytes: Bytes, budget: WorkBudget, cancellation: &CancellationToken, ) -> FsResult<()>

Replaces one file range with caller bytes, preserving sparse untouched ranges.

Errors

Returns measured path, blob, mutation, storage, cancellation, allocation, or bounded-work failures.

pub async fn detach_regular_file( &mut self, path: &NamespacePath, budget: WorkBudget, cancellation: &CancellationToken, ) -> FsResult<DetachedFile<A, O>>

Captures one regular file as an ephemeral path-independent open view.

The returned file shares authenticated immutable objects with this volume. Its later mutations are visible only through copies of this detached value and are never published into a generation.

Errors

Returns typed absence, non-regular kind, path, storage, cancellation, dependency, or bounded-work failures.

pub async fn read_file_record_by_id( &mut self, file_id: FileId, budget: WorkBudget, cancellation: &CancellationToken, ) -> FsResult<FileRecord>

Reads one authenticated candidate file record by stable identity.

Tracking modes retain a complete file-record dependency. More precise byte and metadata APIs below retain only their semantic regions.

Errors

Returns typed absence, authentication, storage, cancellation, dependency, allocation, or bounded-work failures.

pub async fn read_file_range_by_id( &mut self, file_id: FileId, range: ByteRange, budget: WorkBudget, cancellation: &CancellationToken, ) -> FsResult<FileRangeRead>

Reads one exact logical range by stable file identity.

Errors

Returns measured absence, non-regular kind, range, authentication, dependency, cancellation, storage, allocation, or bounded-work failures.

pub async fn read_file_up_to_by_id( &mut self, file_id: FileId, offset: u64, maximum_bytes: u32, budget: WorkBudget, cancellation: &CancellationToken, ) -> FsResult<FileRangeRead>

Reads at most maximum_bytes, clipping to the current logical EOF in the same checkout view used to read content.

Errors

Returns the same typed failures as Self::read_file_range_by_id.

pub async fn plan_file_extents_by_id( &mut self, file_id: FileId, range: ByteRange, maximum_spans: u32, budget: WorkBudget, cancellation: &CancellationToken, ) -> FsResult<Option<ExtentPlan>>

Plans one bounded sparse range by stable file identity without reading content blobs or resolving namespace bindings.

None identifies inline regular content. Tracking modes retain the exact byte-range dependency represented by the returned plan.

Errors

Returns measured absence, non-regular kind, invalid bounds, authentication, dependency, cancellation, allocation, storage, or bounded-work failures.

pub async fn seek_file_extent_by_id( &mut self, file_id: FileId, offset: u64, target: ExtentSeekTarget, budget: WorkBudget, cancellation: &CancellationToken, ) -> FsResult<Option<u64>>

Finds the first sparse data or hole boundary by stable file identity.

Errors

Returns measured absence, non-regular kind, malformed extent, dependency, cancellation, storage, allocation, or bounded-work failures.

pub async fn read_metadata_by_id( &mut self, file_id: FileId, budget: WorkBudget, cancellation: &CancellationToken, ) -> FsResult<FileMetadata>

Reads complete canonical metadata by stable file identity.

Errors

Returns measured absence, authentication, decode, dependency, storage, cancellation, allocation, or bounded-work failures.

pub async fn read_named_attribute_by_id( &mut self, file_id: FileId, name: &AttributeName, budget: WorkBudget, cancellation: &CancellationToken, ) -> FsResult<Option<Bytes>>

Reads one exact named attribute by stable file identity.

Errors

Returns measured metadata, attribute-tree, blob, storage, authentication, cancellation, allocation, or bounded-work failures.

pub async fn list_named_attributes_by_id( &mut self, file_id: FileId, after: Option<&AttributeName>, maximum_entries: u32, budget: WorkBudget, cancellation: &CancellationToken, ) -> FsResult<AttributeListing>

Lists one bounded page of named attributes by stable file identity.

Errors

Returns measured metadata, pagination, storage, authentication, cancellation, allocation, or bounded-work failures.

pub async fn write_named_attribute_by_id( &mut self, file_id: FileId, name: AttributeName, value: Bytes, mode: NamedAttributeWriteMode, budget: WorkBudget, cancellation: &CancellationToken, ) -> FsResult<()>

Inserts or replaces one named attribute by stable file identity.

Errors

Returns measured precondition, metadata, blob, attribute-tree, storage, mutation, cancellation, allocation, or bounded-work failures.

pub async fn remove_named_attribute_by_id( &mut self, file_id: FileId, name: AttributeName, budget: WorkBudget, cancellation: &CancellationToken, ) -> FsResult<()>

Removes one named attribute by stable file identity.

Errors

Returns authenticated absence or the same measured failures as Self::write_named_attribute_by_id.

pub async fn write_file_by_id( &mut self, file_id: FileId, offset: u64, bytes: Bytes, budget: WorkBudget, cancellation: &CancellationToken, ) -> FsResult<()>

Replaces one range of an attached regular file by stable identity.

Errors

Returns measured blob, mutation, storage, cancellation, allocation, or bounded-work failures. Authenticated absence never scans the namespace.

pub async fn set_metadata_by_id( &mut self, file_id: FileId, metadata: FileMetadata, budget: WorkBudget, cancellation: &CancellationToken, ) -> FsResult<()>

Replaces complete canonical metadata by stable identity.

Errors

Returns measured encoding, storage, mutation, cancellation, allocation, or bounded-work failures.

pub async fn set_attributes_by_id( &mut self, file_id: FileId, metadata: FileMetadata, logical_bytes: Option<u64>, budget: WorkBudget, cancellation: &CancellationToken, ) -> FsResult<()>

Replaces complete metadata and optionally logical size as one attached file-table transaction.

Errors

Returns measured encoding, storage, sparse mutation, cancellation, allocation, or bounded-work failures. The candidate record changes only if the complete ordered batch succeeds.

pub async fn resize_file_by_id( &mut self, file_id: FileId, logical_bytes: u64, budget: WorkBudget, cancellation: &CancellationToken, ) -> FsResult<()>

Changes logical length by stable identity.

Errors

Returns the same measured failures as Self::mutate.

pub async fn zero_file_range_by_id( &mut self, file_id: FileId, range: ByteRange, allocated: bool, extend: bool, budget: WorkBudget, cancellation: &CancellationToken, ) -> FsResult<()>

Punches a hole or writes allocated zeros by stable identity.

Errors

Returns the same measured failures as Self::mutate.

pub async fn preallocate_file_by_id( &mut self, file_id: FileId, range: ByteRange, keep_size: bool, budget: WorkBudget, cancellation: &CancellationToken, ) -> FsResult<()>

Allocates sparse holes by stable identity.

Errors

Returns the same measured failures as Self::mutate.

pub async fn clone_file_range_by_id( &mut self, source_file_id: FileId, source_offset: u64, destination_file_id: FileId, destination_offset: u64, length: u64, budget: WorkBudget, cancellation: &CancellationToken, ) -> FsResult<()>

Clones one sparse logical range between stable identities.

Errors

Returns the same measured failures as Self::mutate.

pub async fn remove( &mut self, path: NamespacePath, expected_file_id: Option<FileId>, budget: WorkBudget, cancellation: &CancellationToken, ) -> FsResult<()>

Removes one namespace binding with an optional exact identity precondition.

Errors

Returns the same measured failures as Self::mutate.

pub async fn rename( &mut self, source: NamespacePath, destination: NamespacePath, replace: bool, budget: WorkBudget, cancellation: &CancellationToken, ) -> FsResult<()>

Atomically renames one binding within this volume.

Errors

Returns the same measured failures as Self::mutate.

pub async fn hard_link( &mut self, source: NamespacePath, destination: NamespacePath, budget: WorkBudget, cancellation: &CancellationToken, ) -> FsResult<()>

Creates another binding to an existing non-directory file.

Errors

Returns the same measured failures as Self::mutate.

pub async fn set_metadata( &mut self, path: NamespacePath, metadata: FileMetadata, budget: WorkBudget, cancellation: &CancellationToken, ) -> FsResult<()>

Replaces the complete canonical metadata record for one existing file.

The encoded metadata object is admitted before the checkout mutation; failed publication can leave only an unreachable immutable object.

Errors

Returns measured metadata encoding, object-storage, cancellation, mutation, allocation, or bounded-work failures.

pub async fn set_attributes( &mut self, path: NamespacePath, metadata: FileMetadata, logical_bytes: Option<u64>, budget: WorkBudget, cancellation: &CancellationToken, ) -> FsResult<()>

Replaces complete metadata and optionally logical size as one path transaction.

Immutable metadata may be staged first, but the candidate changes only when both the metadata and optional sparse resize validate and apply.

Errors

Returns measured encoding, storage, sparse mutation, cancellation, allocation, or bounded-work failures.

pub async fn resize_file( &mut self, path: NamespacePath, logical_bytes: u64, budget: WorkBudget, cancellation: &CancellationToken, ) -> FsResult<()>

Changes a regular file’s logical length while preserving sparse semantics.

Errors

Returns the same measured failures as Self::mutate.

pub async fn zero_file_range( &mut self, path: NamespacePath, range: ByteRange, allocated: bool, extend: bool, budget: WorkBudget, cancellation: &CancellationToken, ) -> FsResult<()>

Punches a hole or preserves physical allocation as canonical zeros.

Errors

Returns the same measured failures as Self::mutate.

pub async fn preallocate_file( &mut self, path: NamespacePath, range: ByteRange, keep_size: bool, budget: WorkBudget, cancellation: &CancellationToken, ) -> FsResult<()>

Allocates sparse holes while preserving all existing file content.

With keep_size = false, the file grows to include the complete range. A keep-size request extending beyond EOF is rejected explicitly because invisible host allocation is not part of the portable authenticated format.

Errors

Returns typed range, capability, sparse-mutation, storage, cancellation, or bounded-work failures.

pub async fn clone_file_range( &mut self, request: FileCloneRequest, budget: WorkBudget, cancellation: &CancellationToken, ) -> FsResult<()>

Clones one logical range by immutable extent reference without reading bytes.

Errors

Returns the same measured failures as Self::mutate.

pub async fn stage_content<R: AsyncBlobSource>( &self, source: &mut R, maximum_source_bytes: u64, budget: WorkBudget, cancellation: &CancellationToken, ) -> FsResult<StagedContent>

Streams caller content into immutable authenticated chunks without materializing the complete source in memory.

The returned reference can be used by AuthoredMutation::CreateFileFromContent or AuthoredMutation::WriteFromContent in one later atomic transaction. Unused staged content is harmless and collectible.

Errors

Rejects zero or volume-exceeding source bounds and returns exact source, storage, cancellation, allocation, encoding, or work-budget failures.

pub async fn commit( &mut self, operation_id: OperationId, budget: WorkBudget, cancellation: &CancellationToken, ) -> FsResult<CheckoutCommitOutcome>

Checkpoints, authenticates, and conditionally publishes this overlay.

The caller supplies a stable operation identity and must reuse it only for an exact retry. Semantic authority conflicts are returned as values; failed or rejected publication leaves the private overlay intact.

Errors

Rejects clean/non-writable checkouts and returns exact checkpoint, closure, authority, cancellation, or budget failures.

pub async fn commit_with_permit( &mut self, operation_id: OperationId, permit: PublicationPermit, budget: WorkBudget, cancellation: &CancellationToken, ) -> FsResult<CheckoutCommitOutcome>

Publishes this overlay only while the supplied durable operation lease remains active at the authority linearization point.

pub async fn lookup_no_follow( &mut self, path: &NamespacePath, budget: WorkBudget, cancellation: &CancellationToken, ) -> FsResult<PathLookup>

Resolves an exact path without following links or scanning unrelated subtrees.

Errors

Returns a measured failure for invalid profile semantics, malformed authenticated routing, missing root records, non-directory traversal, cancellation, backend failure, or budget exhaustion.

pub async fn lookup_no_follow_with_metadata( &mut self, path: &NamespacePath, budget: WorkBudget, cancellation: &CancellationToken, ) -> FsResult<Option<PathMetadataLookup>>

Resolves one exact path and decodes its authenticated metadata without repeating the namespace or file-table traversal.

Errors

Returns the lookup failures plus bounded object-read or metadata-decode failures. Authenticated absence performs no metadata read.

pub async fn lookup_batch_no_follow( &mut self, paths: &[NamespacePath], budget: WorkBudget, cancellation: &CancellationToken, ) -> FsResult<PathBatchLookup>

Resolves a bounded path batch while sharing directory and file-table frontiers.

Input order and duplicates are preserved. The operation never follows links, reads file bodies, or scans unrelated namespace subtrees.

Errors

Returns the same measured fail-closed outcomes as Self::lookup_no_follow, plus explicit empty and excessive-batch rejection.

pub async fn list_directory( &mut self, path: &NamespacePath, after: Option<&LogicalName>, maximum_entries: u32, budget: WorkBudget, cancellation: &CancellationToken, ) -> FsResult<DirectoryPage>

Returns one bounded authenticated page from a directory.

Tracking checkouts retain the exact cursor interval as an observation, preventing an automatic rebase from crossing inserted or removed names.

Errors

Returns measured path, kind, pagination, dependency, storage, cancellation, or bounded-work failures.

pub async fn list_directory_records( &mut self, path: &NamespacePath, after: Option<&LogicalName>, maximum_entries: u32, budget: WorkBudget, cancellation: &CancellationToken, ) -> FsResult<DirectoryRecordPage>

Returns one directory page with all child records fetched in one shared authenticated file-table batch.

This is the native-mount enumeration surface: it avoids one path lookup per child while preserving the same cursor observation as Self::list_directory.

Errors

Returns the listing failures plus authenticated file-table failures or a typed namespace/file-table consistency error.

pub async fn read_metadata( &mut self, path: &NamespacePath, budget: WorkBudget, cancellation: &CancellationToken, ) -> FsResult<FileMetadata>

Reads complete canonical metadata for one exact path.

Tracking checkouts retain the metadata identity independently from file content, allowing unrelated content changes to rebase safely.

Errors

Returns measured absence, path, decode, dependency, storage, cancellation, or bounded-work failures.

pub async fn read_named_attribute( &mut self, path: &NamespacePath, name: &AttributeName, budget: WorkBudget, cancellation: &CancellationToken, ) -> FsResult<Option<Bytes>>

Reads one exact named attribute without reading unrelated attribute payloads or pages.

Errors

Returns measured path, metadata, attribute-tree, blob, cancellation, storage, allocation, or bounded-work failures.

pub async fn list_named_attributes( &mut self, path: &NamespacePath, after: Option<&AttributeName>, maximum_entries: u32, budget: WorkBudget, cancellation: &CancellationToken, ) -> FsResult<AttributeListing>

Lists one bounded page of exact named-attribute identities without reading any attribute payload bytes.

Errors

Returns measured path, metadata, pagination, cancellation, storage, allocation, or bounded-work failures.

pub async fn write_named_attribute( &mut self, path: NamespacePath, name: AttributeName, value: Bytes, mode: NamedAttributeWriteMode, budget: WorkBudget, cancellation: &CancellationToken, ) -> FsResult<()>

Inserts or replaces one named attribute and atomically updates the path’s metadata reference in the checkout candidate.

Immutable payload and attribute pages are staged first; a rejected precondition can leave only unreachable authenticated objects.

Errors

Returns measured precondition, path, blob, attribute-tree, metadata, mutation, cancellation, storage, allocation, or bounded-work failures.

pub async fn remove_named_attribute( &mut self, path: NamespacePath, name: AttributeName, budget: WorkBudget, cancellation: &CancellationToken, ) -> FsResult<()>

Removes one existing named attribute and atomically updates metadata.

Errors

Returns FsError::NotFound for authenticated absence and otherwise the same bounded failures as Self::write_named_attribute.

pub async fn plan_file_extents( &mut self, path: &NamespacePath, range: ByteRange, maximum_spans: u32, budget: WorkBudget, cancellation: &CancellationToken, ) -> FsResult<Option<ExtentPlan>>

Plans the sparse physical representation of one exact regular-file range.

None identifies tiny inline content; callers should use Self::read_file_range for that bounded body. A returned plan contains holes, allocated-zero spans, and immutable-content spans without reading content blobs or unrelated extent pages.

Errors

Returns measured path, kind, range, authentication, dependency, cancellation, storage, allocation, excessive-span, or bounded-work failures.

pub async fn seek_file_extent( &mut self, path: &NamespacePath, offset: u64, target: ExtentSeekTarget, budget: WorkBudget, cancellation: &CancellationToken, ) -> FsResult<Option<u64>>

Finds the first sparse data or hole boundary after one logical offset.

Namespace and extent roots are resolved once. The extent traversal then advances monotonically across authenticated leaf frontiers without reading file bodies or restarting at the root.

Errors

Returns measured absence, non-regular kind, invalid offset, malformed extent graph, cancellation, backend, dependency, or bounded-work failures.

pub async fn read_file_range( &mut self, path: &NamespacePath, range: ByteRange, budget: WorkBudget, cancellation: &CancellationToken, ) -> FsResult<FileRangeRead>

Reads one exact logical regular-file range without materializing holes or unrelated extent and blob subtrees.

Errors

Returns measured path, kind, range, authentication, dependency, cancellation, storage, allocation, or bounded-work failures.