Struct Generation 

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

Immutable complete filesystem state belonging to one workspace.

Implementations

impl<A, O> Generation<A, O>

pub const fn id(&self) -> GenerationId

Content-addressed generation identity.

pub const fn workspace_id(&self) -> WorkspaceId

Owning workspace identity.

pub fn workspace(&self) -> Workspace<A, O>

Returns the workspace capability that owns this immutable generation.

The returned handle is cheap and retains the same authenticated storage deployment. It is useful for composing generation-oriented algorithms without an adapter-owned workspace registry.

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

pub async fn reader(&self) -> Result<PinnedReader<A, O>, WorkspaceError>

Opens one cheap immutable reader pinned to this exact generation.

The generation root is authenticated once while the reader is opened; descendant objects remain lazy and are fetched only by the operation that needs them. Clone the returned reader to overlap independent requests without reopening the generation.

Errors

Rejects unavailable, foreign, or corrupt generation state and bounded backend failures.

pub async fn diff_to( &self, to: &Generation<A, O>, maximum_changes: u32, ) -> Result<ChangeSet<A, O>, WorkspaceError>

Computes one semantic delta to a compatible generation in any workspace from the same filesystem deployment.

pub async fn diff_to_bounded( &self, to: &Generation<A, O>, maximum_changes: u32, budget: WorkBudget, cancellation: &CancellationToken, ) -> Result<ChangeSet<A, O>, WorkspaceError>

Computes one semantic delta with explicit cumulative work and cancellation bounds.

pub async fn materialize( &self, options: &MaterializeOptions, budget: WorkBudget, cancellation: &CancellationToken, ) -> Result<OperationReceipt<MaterializationReceipt>, WorkspaceError>

Materializes this immutable generation into an existing empty host directory using the SDK’s native capability-rooted adapter. Unix ctime and Linux birth time are host-generated view-local facts; their exact canonical values remain in this generation, not in the host inode.

pub async fn materialize_path( &self, path: &str, options: &MaterializeOptions, budget: WorkBudget, cancellation: &CancellationToken, ) -> Result<OperationReceipt<MaterializationReceipt>, WorkspaceError>

Materializes one path from this generation below an existing empty host directory. The same relative path is reproduced below the destination, allowing callers to stage and atomically exchange it.

pub async fn materialize_paths( &self, paths: &[String], options: &MaterializeOptions, budget: WorkBudget, cancellation: &CancellationToken, ) -> Result<OperationReceipt<MaterializationReceipt>, WorkspaceError>

Materializes multiple paths with one pinned checkout and shared file-identity table, preserving hard links across selected paths.

pub async fn restore_host_path( &self, relative: &Path, replacement: HostPathReplacement, options: &MaterializeOptions, budget: WorkBudget, cancellation: &CancellationToken, ) -> Result<OperationReceipt<HostPathRestore>, WorkspaceError>

Restores one path from this immutable generation into a host tree.

Only the selected path is read and touched. Publication is same-volume and atomic for an ordinary host tree, or mount-visible for a live mount.

pub async fn restore_host_paths( &self, paths: &[PathBuf], replacement: HostPathReplacement, options: &MaterializeOptions, cancellation: &CancellationToken, ) -> Result<Vec<HostPathRestore>, WorkspaceError>

Restores a bounded sequence of paths through one pinned checkout.

pub async fn parents(&self) -> Result<Vec<GenerationId>, WorkspaceError>

Returns the exact immutable parent generation identities.

Errors

Returns an authenticated storage or identity failure for malformed state.

pub async fn read( &self, path: &str, maximum_bytes: u64, ) -> Result<Bytes, WorkspaceError>

Reads at most maximum_bytes from one complete file in this exact immutable generation.

Errors

Rejects invalid, absent, non-file, oversized, or unauthenticated state.

pub async fn read_range( &self, path: &str, offset: u64, length: u64, ) -> Result<Bytes, WorkspaceError>

Reads one exact range from this immutable generation.

Errors

Rejects invalid/absent/non-file paths, invalid ranges, and authenticated backend failures.

pub async fn stat(&self, path: &str) -> Result<WorkspaceStat, WorkspaceError>

Returns complete metadata for one path in this immutable generation.

Errors

Rejects invalid or absent paths and authenticated backend failures.

pub async fn lookup_paths( &self, paths: &[NamespacePath], budget: WorkBudget, cancellation: &CancellationToken, ) -> FsResult<Vec<Option<FileRecord>>>

Resolves an ordered exact path batch while sharing authenticated directory and file-table frontiers. Absence is returned as None; links are not followed and file bodies are not read.

Errors

Rejects an empty or excessive batch, foreign path encodings, cancellation, and authenticated backend failures.

pub async fn list_directory( &self, path: &str, after: Option<&LogicalName>, maximum_entries: u32, ) -> Result<WorkspaceDirectoryPage, WorkspaceError>

Returns one authenticated bounded directory page from this generation.

Errors

Rejects invalid/absent/non-directory paths, invalid cursors or bounds, and authenticated backend failures.

pub async fn paths_for_file_id( &self, file_id: FileId, maximum_entries: u32, ) -> Result<Vec<String>, WorkspaceError>

Finds portable paths bound to one stable file identity in this generation.

The traversal is bounded by maximum_entries; results are sorted and include every matching hard link encountered before that bound.

pub async fn paths_for_file_ids( &self, file_ids: impl IntoIterator<Item = FileId>, maximum_entries: u32, ) -> Result<BTreeMap<FileId, Vec<String>>, WorkspaceError>

Finds portable paths for multiple stable file identities in one namespace traversal.

The traversal is bounded by maximum_entries; each result is sorted and includes every matching hard link encountered before that bound. Identities without a matching binding are omitted.

pub async fn read_symbolic_link( &self, path: &str, ) -> Result<Bytes, WorkspaceError>

Reads one opaque symbolic-link target from this generation.

Errors

Rejects invalid/absent/non-symbolic-link paths and authenticated backend failures.

pub async fn plan_extents( &self, path: &str, offset: u64, length: u64, maximum_spans: u32, ) -> Result<WorkspaceExtentPlan, WorkspaceError>

Plans sparse logical spans without reading content bodies.

Errors

Rejects invalid/absent/non-file paths, invalid ranges or bounds, and authenticated backend failures.

pub async fn pin( &self, identity: impl AsRef<str>, ) -> Result<GenerationPin<A, O>, WorkspaceError>

Retains this exact immutable generation under one opaque stable identity.

Errors

Rejects invalid identities, foreign or corrupt generation state, and conflicting reuse of an existing pin identity.

Trait Implementations

impl<A, O> Clone for Generation<A, O>

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.