Skip to main content

Module promote

Module promote 

Source
Expand description

Promote saga — snapshot the node-local upper layer into a content-addressed registry commit, then advance the atproto pointer record.

§What promote does

The writable union (#394) buffers writes in a node-local, append-only upper layer (the existing overlayfs upper + a journal). Promote is the operation that turns those buffered edits into an immutable, distributed snapshot:

  1. Stage + commit locally via the existing WorktreeClient::stage_all / commit RPCs (registry.capnp). This produces a deterministic git commit: two nodes promoting byte-identical upper-layer content produce identical commit OIDs (the stageAll→commit path is deterministic given identical index + tree state).
  2. Advance the atproto pointer record so federated peers see the new head. This is the only step that touches the PDS.

§Single-writer-per-layer (Shapiro)

A layer may be promoted by at most one node at a time. We enforce this at the promote entry point with a per-layer lease (the PromoteLease). The lease is held for the duration of the local commit; the PDS write that follows is idempotent (atproto putRecord is last-writer-wins on the record rkey), so a crashed promote that already committed locally simply re-runs and advances the pointer on retry.

§Eventual consistency, not atomicity

Promote spans two stores: the local git repo and the atproto PDS. We do not pretend this is atomic. The local commit happens first and is durable; the PDS record update happens second. If the PDS write fails after the local commit succeeds:

  • The content is committed locally and reachable via the git ref.
  • The atproto pointer is stale — it still points at the previous head.
  • The next successful promote advances the pointer to the latest local head, skipping the stale intermediate. Because git commits are content-addressed and parent-chained, no commit is lost: the stale pointer simply lags until a later promote catches up.

This is the honest treatment. A two-phase-commit across git + atproto would require a PDS that supports prepare/commit, which atproto does not; the pointer-record pattern is the standard atproto eventual-consistency primitive (it is how Bluesky itself advances collection pointers).

§No new RPC

Promote reuses the existing stageAll + commit worktree verbs from registry.capnp. The PDS record write is a plain HTTPS putRecord call, not a hyprstream RPC — the atproto substrate (#355/#410) owns that client.

Structs§

PromoteAuthor
The node identity used to author the promote commit and the atproto record.
PromoteLease
A held per-layer promote lease. Dropping it releases the layer for other nodes to promote.
PromoteLeaseTable
Per-process registry of held promote leases, keyed by {repo}:{worktree}.
PromoteOutcome
Outcome of a successful promote.

Enums§

PromoteError
An error from the promote saga.

Functions§

promote
Run the promote saga for a single worktree.