Struct Workspace 

pub struct Workspace { /* private fields */ }

A named, versioned body of work content with its own histories and journal. The root engine is source zero; each mounted source carries its own engine and history (ADR-0009).

Implementations

impl Workspace

pub fn init(path: impl AsRef<Path>) -> Result<Self, Error>

Turn path into a workspace: control dir, journal, and engine store.

pub fn open(path: impl AsRef<Path>) -> Result<Self, Error>

Open the workspace already present at path.

pub fn actor(&self) -> &Actor

The actor this workspace handle acts as.

pub fn attach(&mut self, folder: impl AsRef<Path>) -> Result<Source, Error>

Attach a local folder, importing its content into the root — source zero. One root import per workspace; mounted sources go through Workspace::attach_mount.

pub fn attach_mount( &mut self, folder: impl AsRef<Path>, name: &str, ) -> Result<Source, Error>

Attach a local folder as a mounted source: its own engine, its own history, at root/<name> (ADR-0009).

pub fn attach_remote(&mut self, url: &str, name: &str) -> Result<Source, Error>

Attach a bucket prefix as a mounted source (ADR-0012): the objects import into the mount, which carries its own engine and history; the listing’s fingerprint guards every later mirror home.

pub fn log(&mut self, limit: usize) -> Result<Vec<SourceSnapshot>, Error>

The shared lines’ snapshots: the root’s, then each mount’s in name order, each newest first, limit applying per source.

pub fn diff_latest(&mut self) -> Result<Diff, Error>

Diff each source’s latest snapshot against its first parent, root first then mounts in name order, every delta raised to the highest rung the ladder allows and mounted addresses scoped by mount.

pub fn manifest(&mut self) -> Result<String, Error>

Render the read model an actor consumes first: identity, sources, discipline, live state, and the loop this workspace expects. Every face returns this text verbatim (ADR-0006: one render, three faces).

pub fn status(&mut self) -> Result<String, Error>

The live-state read model: what the manifest’s state section says, standing alone. Every face returns this text verbatim (ADR-0006).

pub fn diff_between(&mut self, before: &str, after: &str) -> Result<Diff, Error>

Diff two of the root line’s snapshots by id: before against after, each delta raised to the highest rung the ladder allows. Mounted lines’ snapshot pairs arrive with the session fan-out.

pub fn journal(&mut self, limit: usize) -> Result<Vec<JournalEntry>, Error>

Read up to limit journal entries, newest first.

pub fn open_session( &mut self, actor: &Actor, instruction: &Instruction, ) -> Result<Session, Error>

Open a session for actor: its own working copy holding the shared head, its own change. Isolation is not optional — every session starts isolated, and only landing serializes.

pub fn sessions(&mut self) -> Result<Vec<Session>, Error>

Every session, newest first. Sessions are durable rows plus real directories: they survive process restarts, and nothing deletes them.

pub fn session(&mut self, id: SessionId) -> Result<Session, Error>

The session named id.

pub fn session_write( &mut self, id: SessionId, path: &str, content: &str, ) -> Result<String, Error>

Write content at path inside the session’s working copy — a mount-scoped path lands in that source’s working copy — and snapshot every source; the id of the written source’s tip snapshot.

pub fn session_read( &mut self, id: SessionId, path: &str, start: usize, max_bytes: Option<usize>, ) -> Result<ReadResult, Error>

Read path inside the session’s working copy, windowed. A document a package projects reads as its projection; plain text reads as itself; anything else refuses — raw byte views arrive with a later slice.

pub fn session_diff(&mut self, id: SessionId) -> Result<Diff, Error>

Each source’s session change against the shared-line snapshot it forked from, raised through the ladder like any diff, mounted addresses scoped by mount. An untouched source contributes nothing.

pub fn request_land(&mut self, id: SessionId) -> Result<LandingRequest, Error>

Open the session’s landing request — the gate’s object, never a direct write (ADR-0007). Asking again returns the request already holding the gate.

pub fn landing_requests(&mut self) -> Result<Vec<LandingRequest>, Error>

Every landing request, newest first.

pub fn request(&mut self, id: RequestId) -> Result<LandingRequest, Error>

The landing request named id.

pub fn approve( &mut self, id: RequestId, approver: &Actor, ) -> Result<GateOutcome, Error>

Record approver’s approval on the request; when the gate is satisfied the apply runs — lease, rebase, advance — landing the change or parking the request on a conflict.

pub fn reject( &mut self, id: RequestId, actor: &Actor, reason: Option<&str>, ) -> Result<LandingRequest, Error>

Reject the request: the gate closes, the session stays open.

pub fn land(&mut self, id: SessionId) -> Result<GateOutcome, Error>

Land the session’s change: sugar for request plus self-approval. Where policy forbids self-approval the request stays pending for other approvers.

pub fn abandon(&mut self, id: SessionId) -> Result<Session, Error>

Close the session without landing; its work stays in history and its working copy stays on disk.

pub fn watch( &mut self, debounce: Duration, on_event: impl FnMut(&WatchEvent), stop: &WatchStop, ) -> Result<(), Error>

Watch the workspace root: external edits become attributed snapshots through the same snapshot path every operation uses. Blocks until stop asks it to return; edits made while no watcher runs are caught up by the scan at start. Each snapshot — and the armed watcher itself — reaches the caller through on_event.

pub fn undo(&mut self, id: RequestId) -> Result<Vec<Restore>, Error>

Step a landed request back off every line it landed (ADR-0011): reverse landing order, each line under its landing lease, idempotent per line. The request re-opens with its approvals dismissed — an undo is a new decision point — and the session re-opens with its change intact, immediately re-landable.

pub fn pull(&mut self, source: Option<&str>) -> Result<PullOutcome, Error>

Fold bucket-side changes into a mounted remote source’s line as one attributed snapshot (ADR-0012, R2). A line that moved locally since its last sync refuses by name - land or sync it first; nothing is pulled over unlanded movement, and the pull’s own auto-snapshot means outstanding edits count as movement, never as loss.

pub fn sync( &mut self, source: Option<&str>, force: bool, ) -> Result<SyncOutcome, Error>

Mirror a folder source’s shared line back to its origin (ADR-0010): guarded by the recorded fingerprint unless force. Git sources refuse by name - bookmark motion is their out-flow. The act is journaled either way.