Crate atelier_sdk

Expand description

The atelier SDK and engine: versioned workspaces humans and AI agents do real work in, with snapshots, isolated sessions, gated landing, and a journal that answers who did what and why.

A Workspace is a directory whose whole history atelier keeps: every outstanding edit becomes an attributed Snapshot before any read model answers. An actor works in a Session — its own working copy, its own change — and lands through the gate: a LandingRequest gathers approvals under the workspace’s LandingPolicy, then the apply lands the change on the shared line or parks on a conflict — never half-applies. Every act becomes a JournalEntry in the append-only journal. Diffs ride a fidelity ladder (Diff): every file compares at least as bytes, text raises to line diffs, and format packages — Word documents via atelier-sdk-docx — raise to deltas in the format’s own terms. A workspace attaches sources — local folders, git repositories, bucket prefixes — each mounted with its own history; landings fan out per source and mirror back.

The CLI and the MCP and HTTP surfaces are thin shells over this crate: anything they do, the SDK does directly.

§Example

The actor comes from config ($ATELIER_CONFIG_HOME/config.toml, else $XDG_CONFIG_HOME/atelier/config.toml, else ~/.config/atelier/config.toml):

use atelier_sdk::{GateOutcome, Instruction, Workspace};

let config = tempfile::tempdir()?;
std::fs::write(
    config.path().join("config.toml"),
    "[actor]\nname = \"ada\"\nkind = \"human\"\n",
)?;

// A workspace, a session, one write, and a landing through the gate.
let root = tempfile::tempdir()?;
let mut workspace = Workspace::init(root.path())?;
let actor = workspace.actor().clone();
let session = workspace.open_session(
    &actor,
    &Instruction {
        summary: "draft the notes".to_owned(),
        run_ref: None,
        verbatim: None,
    },
)?;
workspace.session_write(session.id, "notes.md", "The first note.\n")?;
let outcome = workspace.land(session.id)?;
assert!(matches!(outcome, GateOutcome::Landed { .. }));

Structs§

Actor: The actor a workspace attributes its snapshots and journal entries to.
Address: Where a delta lands, in the format’s own terms.
Approval: A recorded grant by an actor toward a request’s gate, tied to the snapshot of the change it covered.
Delta: One addressed difference inside a Diff, carried at its own rung.
Diff: The differences between two versions: addressed deltas, each carried at the highest fidelity the ladder could raise it to.
Instruction: The task or prompt that drove a session’s acts. The journal keeps the summary and run reference; verbatim capture is policy-decided (ADR-0004).
JournalEntry: One record in a workspace’s journal: who did what, and any intent behind it.
JournalPolicy: The [journal] policy: how much of a session’s instruction the journal keeps (ADR-0004).
Landing: One source’s landing under a request: the root’s when source is None; the source’s shared line’s new head.
LandingPolicy: The [landing] policy: what a landing request needs before its change lands (ADR-0007). The default profile takes one approval, allows self-approval, and dismisses approvals when the change gains a snapshot.
LandingRequest: A change’s application to land on the shared line (ADR-0007): its requester and the approvals its gate has gathered, open until it lands, parks, or closes.
Line: One line of a text-rung comparison: what happened and the line’s content.
PackageId: The identity of a format package: its name plus semver version.
ReadResult: One windowed read: bounded content plus the cursor to continue from.
ReadWindow: Where in the text a read’s content sits, in bytes of the text read — the projection’s for a projected document, the document’s own otherwise.
RequestId: A landing request’s identity: r plus its row in the workspace store.
Restore: One line a landed request stepped back off (ADR-0011): the source and the head the line returned to.
Session: One actor’s bounded run of work in a workspace: its own working copy, its own change, journal entries grouped under it.
SessionId: A session’s identity: s plus its row in the workspace store.
Snapshot: One immutable whole-workspace state in history, attributed to an actor.
Source: An external origin the workspace is attached to, as held in memory and as persisted under [[source]] in .atelier/config.toml. The mount names the subdirectory whose engine carries the source’s history; / is the v1 root import — content folded into source zero, no engine of its own.
SourceChange: One source’s change under a session: the root’s when source is None.
SourceSnapshot: One snapshot in one source’s history: the root’s when source is None, else the named mount’s.
WatchStop: Stops a running watch loop from another thread; the loop returns within its tick. Outstanding edits stay for the next watcher’s catch-up scan.
Workspace: 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).

Enums§

Act: One thing an actor can do to a workspace that the journal records.
ActorKind: What kind of actor acted: a person, an AI agent, or an automation.
Confidence: How strongly a package claims a document.
DeltaKind: What kind of change one Delta records.
Error: Every way a core operation can fail.
Fidelity: The rung a delta is carried at: the format-independent fidelity ladder.
GateOutcome: What a landing attempt produced. The apply fans out per source (ADR-0009): every landing that happened is recorded and stands, whatever the sources after it did.
InstructionFidelity: What the journal records of an instruction: the summary plus run reference, or additionally the verbatim body (audit profiles).
LineKind: What happened to one line at the text rung.
PullOutcome: The outcome of one pull attempt (ADR-0012, R2).
RequestState: Where a landing request stands in its gate.
SessionState: Where a session stands: open for work, its change landed, or closed without landing.
SourceKind: The kind of origin a source is.
SyncOutcome: The outcome of one sync-back attempt (ADR-0010).
SyncPolicy: How content moves between a workspace and its source.
WatchEvent: What a running watch loop reports as it works.

Constants§

READ_WINDOW_MAX: The most bytes one read returns; also the default window. No unbounded responses exist on the surface.

Functions§

is_remote_url: Whether a source path is a remote URL this adapter speaks.
printable: The line with control characters escaped, so a diffed document cannot inject escape sequences into the terminal that reads it; tabs stay literal. Bidi formatting characters escape too — they are not char::is_control, but they can visually reorder or conceal diff content.
render_diff: The diff as printable lines: every face renders the same comparison through this one path (ADR-0006).