Struct Checkpoint 

pub struct Checkpoint { /* private fields */ }

Implementations

impl Checkpoint

pub fn base_checkpoint( self, scopes: &[String], t: TimeMs, of: &Provenance, progress: &mut dyn FnMut(BaseProgress), ) -> Result<Payload, StorageError>

Stages scopes, scans them and commits, with every object held in memory until the end and then written as one pack.

Takes the handle by value: the in-memory store is installed on this handle’s object database and cannot be taken off again, so the handle goes with it, and no later checkpoint can write an object into a store nobody dumps (crates/storage/spec/Checkpoint.lean §8-8).

The commit moves HEAD when the city has none, under HEAD_MOVES and by compare-and-swap (storage D27), and is otherwise filed under refs/sprawling/runs/<run>/<oid> like a wave checkpoint.

Errors

Propagates staging, the staged-secret scan, the commit, a pack the object database refuses, a reference it will not write, and a HEAD another writer created after this one read it as absent.

impl Checkpoint

pub fn ensure_base( &mut self, scopes: &[String], t: TimeMs, of: &Provenance, ) -> Result<Option<Payload>, StorageError>

Makes sure the city has one commit, and makes no more than that.

A worktree branches from a commit, so a city that has never been checkpointed cannot lend a tree. Committing on every dispatch would move the trunk under every request already waiting. Returns the commit it made, or None when there already was one.

The commit is written the way Checkpoint::base_checkpoint writes one: every object in memory, then one pack, then the index and the branch, so a city of N files pays one file write for its objects rather than N, and a refusal leaves the index and HEAD as they were.

Errors

Propagates whatever staging, scanning, packing and committing report.

pub fn wave_pre( &mut self, scopes: &[String], t: TimeMs, of: &Provenance, ) -> Result<Payload, StorageError>

The pre-wave checkpoint: stage everything under scopes, scan it, and commit at the injected time. Returns the checkpoint_committed payload.

scopes is the run’s write domain, not its room (crates/storage/spec/Checkpoint/Provenance.lean §8-18). The two were allowed to differ once, and every file a resident wrote between them - a building’s own documents, a second declared prefix - was staged by no checkpoint, reported by no changes query, and restorable from no file_discarded record.

The branch does not move: the commit is written with no reference update and pointed at by refs/sprawling/runs/<run>/<oid>, so a person whose own folder became this city keeps their own history instead of one checkpoint: line per tool wave. The oid means what it always meant - the tree is there and wave_post restores from it.

Errors

Propagates staging, the staged-secret scan, the commit, and a reference the repository will not write.

pub fn restore( &self, address: &Address, oid: &GitOid, ) -> Result<(), StorageError>

The way back a file_discarded names: the blob at address in commit oid, written to the same path under the working tree.

Neither the index nor HEAD moves: putting a file back is not a commit, and a person who restored one file should not find a new line in their own branch’s history. A link on the path, or a file already at the target with other bytes, is refused rather than followed or overwritten.

Errors

A commit the repository no longer holds (the checkpoint reference is what keeps one), a path that commit does not hold as a file, a bare repository, an address in the protected metadata subtree (Address::is_reserved), and a write the file system refuses; StorageError::Alias when a symbolic link or junction sits on the path below the working tree, because Address bounds the spelling of a path and not where the disk resolves it.

pub fn take_back( &self, address: &Address, point: &GitOid, ) -> Result<FileRestored, StorageError>

Takes address back from point into the city’s own working tree: the point’s bytes in place of what is there, or no file when the point holds none (crates/storage/spec/Checkpoint.lean §8-33). Returns the file_restored record of this step, name empty for this tree.

Errors

What Checkpoint::restore refuses for the path and the commit, something other than a file at address in point, and a write or a removal the file system refuses.

impl Checkpoint

pub fn open(city_root: &Path) -> Result<Checkpoint, StorageError>

Opens the city repository, initialising one when absent. The genesis commit is the first wave’s, not this call’s: an empty repository is a valid state, and inventing history here would make the first checkpoint unattributable.

Initialises only where there is no repository: a repository that is there and does not open (a damaged .git, a permission refused) is refused, because initialising over it would hide the history it holds.

Errors

A repository that is there and does not open, one that cannot be initialised, and a configuration that cannot be read or written.

pub fn open_writer( root: &Path, writer: RunId, ) -> Result<Checkpoint, StorageError>

A handle that stages into writer’s own index under <root>/.sprawling/index/<run>, seeded from the repository’s index so the first checkpoint still skips unchanged files by their stat.

Errors

No repository at root (writers never create one), and an index file that cannot be seeded or opened.

pub fn close_writer(self) -> Result<(), StorageError>

Deletes this writer’s index file once its run has landed. A handle on the repository’s own index deletes nothing.

Errors

A file the file system will not delete.

pub fn sweep_writers(root: &Path) -> Result<usize, StorageError>

Deletes every private index under root, and answers how many. Called when the city opens, when no run is live, so every one of them is what a crash left behind.

Errors

A directory that cannot be listed and a file that will not delete.

impl Checkpoint

pub fn scan_staged(&mut self) -> Result<(), StorageError>

Scans what this checkpoint would newly write into the tree. Reports how many shapes matched and where, never what matched.

pub fn land( &mut self, scopes: &[String], t: TimeMs, of: &Provenance, subject: &str, ) -> Result<String, StorageError>

Puts this tree on the branch, under the session that produced it.

This is what a reviewing run does when it offers its work: the wave checkpoints behind it are dangling commits nobody merges, and what a verifier judges has to be a commit on the run’s own branch. Time stays a parameter here as everywhere else — the signature carries the injected instant, so the same script lands the same oid.

Only scopes is staged, as a checkpoint stages it: a kept tree is checked out again over its scope alone, so its files outside the scope may trail the branch, and staging them would take back what the trunk changed there (crates/storage/spec/Worktree.lean §8-9). Entries outside the scope go into the commit as the index holds them. No scope stages the whole tree except the reserved subtree, whose rule [StageFilter] owns.

Errors

Propagates staging, the staged-secret scan, and the commit.

impl Checkpoint

pub fn wave_post(&mut self, pre_oid: &str) -> Result<Vec<Payload>, StorageError>

The post-wave sweep: every path present at pre_oid and gone from the working tree becomes a file_discarded payload whose restoration points back into that commit.

The question is existence, and only existence. The tree is walked once and each blob is looked for on disk; a path that is not there is a deletion. Asking git for the tree-to-workdir diff instead would hash every path the tree and the worktree agree on, and the city itself keeps writing some of those paths after the checkpoint (a room’s session projection, a worktree under a lease); a hash taken through a Windows directory entry that trails the open handle refuses the whole sweep. A sweep needs Deleted deltas, and a deletion is answered without reading any content.

The tree is the checkpoint’s own write domain, not the whole city: wave_pre walked exactly these paths before the wave began, so the walk costs what staging already cost.

Errors

Propagates a pre_oid that is not an object, a commit whose tree cannot be read, and a working-tree path that cannot be examined.