Workspace contract

WorkspaceProvider is the public contract for capturing, verifying, and forking a workspace. The single-repository Git provider is the default.

Capture and verify

Capture records the repository revision and file state. Verify reads the repository again and reports changed revisions or paths. A caller can pause a run when verification names paths changed by a foreign write. The safe order is capture, verify, acquire the lease, let the caller record the planned child branch, then fork it. Capture reads file states and the content fingerprint concurrently. A write between those reads can mix evidence from two moments. Keep the workspace stable during capture. Dirty-file states retain one digest per line, so a large dirty file can produce a large anchor.

import { createGitWorktreeProvider } from '@obversa/runtime';

const workspace = createGitWorktreeProvider({ repositoryPath: process.cwd() });
const anchor = await workspace.capture();
const verified = await workspace.verify(anchor);
if (!verified.ok) throw new Error('Workspace changed before use.');

const lease = await workspace.acquireLease('example-runner', 'repository', anchor);
if (!lease.ok) throw new Error(`Lease unavailable: ${lease.kind}`);

try {
  const child = await workspace.fork(anchor, 'example-child', lease.token);
  if (!child.ok) throw new Error(`Fork failed: ${child.kind}`);
  console.log(child.branchRef, child.worktreePath);
} finally {
  await workspace.releaseLease(lease.token);
}

Scoped capture

Pass Git path selectors, called pathspecs, to capture(scope) to limit the file states stored in the anchor. The anchor stores the scope. verify uses the same pathspecs. The provider does not check that a pathspec matches a file. A scope with no matches can therefore store no file states. The scope does not limit HEAD. A commit outside the scope still invalidates the anchor. verify compares the repository identity, HEAD, and stored file states. It does not compare the anchor fingerprint. Explicitly selected ignored files can affect that fingerprint without appearing in the stored file states, so verification can miss changes to them.

Leases

A lease allows one writer for one repository. It records the owner, scope, a digest of the workspace anchor, and the acquisition token. Fork accepts only the token for the exact anchor being forked. The Git provider stores the complete record in Git itself. One private Git name points to that record. Acquisition creates the name only when it does not exist. Release requires the token, then removes the name only if it still points to the same record. A delayed release or recovery cannot remove a later owner’s record. Recovery can remove an unreadable stored record. A failed Git blob read marks the record as corrupt, so recovery can remove its ref. This can happen even when the unread record contains a completed lease. Recovery does not remove a completed lease that it can read. It can remove a readable incomplete record after its age limit. Acquisition writes a complete record before it publishes the ref.

Fork failure kinds

Kind	Meaning
`unleased`	No valid lease covers this anchor.
`anchor-changed`	The repository or captured files no longer match the anchor.
`no-revision`	The repository has no commit to fork.
`invalid-child`	The child identifier is not a safe Git branch and directory name.
`exists`	The child branch or worktree already exists.
`incomplete`	The branch exists, but its worktree was not created. A retry can finish it.

Child worktree location

The Git provider creates child worktrees beside the repository, outside its working tree. For /work/project, child review-1 is created at /work/project.obversa-worktrees/review-1. The location is fixed in version 1. A successful fork returns a full capture of the child worktree. Its anchor has scope: null, even when the parent anchor had a scope.

Limits

One repository. The built-in provider captures one Git repository. A multi-repository provider is not included.
Caller-owned run control. Verify reports drift. The caller decides when to pause a run and records any branch or merge events.
No automatic executor binding. The graph executor does not capture, verify, or lease a workspace for the caller.
No forced lease takeover. A readable completed lease remains held until its owner releases it.
No orphan cleanup. The provider can retry an incomplete fork, but it does not remove abandoned child refs or worktrees.

The provider passes its cancellation signal to snapshot helpers. Its own Git calls for leases, refs, and worktrees do not use that signal.

Start

Concepts

Memory

Workspace

Graphs

Proof

Storage

Runtime

Processes

Hosts

Packages

Workspace contract

Capture and verify

Scoped capture

Leases

Fork failure kinds

Child worktree location

Limits

​Capture and verify

​Scoped capture

​Leases

​Fork failure kinds

​Child worktree location

​Limits

Capture and verify

Scoped capture

Leases

Fork failure kinds

Child worktree location

Limits