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:
- Stage + commit locally via the existing
WorktreeClient::stage_all/commitRPCs (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). - 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§
- Promote
Author - The node identity used to author the promote commit and the atproto record.
- Promote
Lease - A held per-layer promote lease. Dropping it releases the layer for other nodes to promote.
- Promote
Lease Table - Per-process registry of held promote leases, keyed by
{repo}:{worktree}. - Promote
Outcome - Outcome of a successful
promote.
Enums§
- Promote
Error - An error from the promote saga.
Functions§
- promote
- Run the promote saga for a single worktree.