Workspace

​

Motivation

​

Lifecycle

• Capture. capture() records the repository’s revision and the state of its files, as an anchor. Pass Git pathspecs to limit it to the files a step may touch.
• Verify. verify(anchor) reads the repository again and reports any changed revision or path. A write you didn’t make shows up here, and you decide whether the run pauses.
• Lease. acquireLease() gives one writer the right to fork that anchor. The lease lives in a private Git ref, so a second writer is refused until the first releases it, and a delayed release can’t remove a later owner’s record.
• Fork. fork(anchor, child, token) creates a child branch and worktree beside the repository, at the anchor’s revision. A fork without a valid lease, or after the anchor changed, fails with a named kind instead of running on stale files.
• Land back. isolated(job) wraps any step in that cycle: it runs the step in its own worktree on a fork branch and, on pass, commits what the step left and merges the branch back, one merge at a time across the process. The worktree is removed and a cleanly merged branch is deleted, so parallel steps leave nothing behind.

​

Example

  const workspace = createGitWorktreeProvider({ repositoryPath: directory });
  const anchor = await workspace.capture();
  const verified = await workspace.verify(anchor);
  if (!verified.ok) throw new Error('workspace changed before fork');
  const lease = await workspace.acquireLease('example', 'workspace-example', anchor);
  if (!lease.ok) throw new Error('lease was not acquired');
  const fork = await workspace.fork(anchor, 'example-child', lease.token);
  await workspace.releaseLease(lease.token);
  if (!fork.ok) throw new Error(`fork failed: ${fork.kind}`);

{"revision":"fab2254b3c8a179cca6aa5063a85d94600d820d5","anchor":"359e3253fb56170c93f1da438494b8da49bf72b3014cbc57e7a9ff711bbdc3c8","branch":"refs/heads/obversa/example-child"}

​

Limits

• One repository. The built-in provider captures one Git repository.
• Not a sandbox. Nothing stops a program outside the run from writing to the checkout. Verify reports that it happened; it doesn’t prevent it.
• You decide what a drift means. Verify reports changed paths. Pausing the run, and recording any branch or merge, is your program’s call. The graph executor doesn’t capture, verify or lease a workspace for you.
• No orphan cleanup. The provider can retry an incomplete fork, but it doesn’t remove abandoned child refs or worktrees.

​

Next steps