pub async fn promote(
repo: &str,
worktree: &str,
wt: &WorktreeClient,
author: &PromoteAuthor,
lease_table: &Arc<PromoteLeaseTable>,
) -> Result<PromoteOutcome, PromoteError>Expand description
Run the promote saga for a single worktree.
repo/worktree identify the layer; wt is the worktree-scoped registry
client (curried repo(id).worktree(name)) whose stage_all / commit
verbs perform the local snapshot; author is the commit + atproto-record
identity; lease_table enforces single-writer-per-layer for this process.
§Determinism
Two nodes promoting byte-identical upper-layer content produce identical
commit OIDs, because stageAll + commit reduce to git add -A +
git commit over a deterministic index, and git commit OIDs are a pure
function of (tree, parents, author, committer, message). The
PromoteAuthor must therefore be a stable identity, not a per-call
ephemeral — the caller is responsible for threading the same author across
competing promotes (the registry service derives it from the verified
Subject).
§Errors
PromoteError::LeaseHeld: another promoter on this node holds the layer’s lease.PromoteError::LocalCommit: the stage/commit RPC failed; nothing was committed.PromoteError::PointerStale: the local commit succeeded but the PDS write failed. The content is committed; the next promote advances the pointer. The caller should surface this as a warning, not a hard failure.