hyprstream_core/git/promote.rs
1//! Promote saga — snapshot the node-local upper layer into a content-addressed
2//! registry commit, then advance the atproto pointer record.
3//!
4//! # What promote does
5//!
6//! The writable union (#394) buffers writes in a node-local, append-only upper
7//! layer (the existing overlayfs upper + a journal). Promote is the operation
8//! that turns those buffered edits into an immutable, distributed snapshot:
9//!
10//! 1. **Stage + commit locally** via the existing `WorktreeClient::stage_all` /
11//! `commit` RPCs (`registry.capnp`). This produces a deterministic git commit:
12//! two nodes promoting byte-identical upper-layer content produce identical
13//! commit OIDs (the stageAll→commit path is deterministic given identical
14//! index + tree state).
15//! 2. **Advance the atproto pointer record** so federated peers see the new
16//! head. This is the only step that touches the PDS.
17//!
18//! # Single-writer-per-layer (Shapiro)
19//!
20//! A layer may be promoted by at most one node at a time. We enforce this at
21//! the promote entry point with a per-layer lease (the
22//! [`PromoteLease`]). The lease is held for the duration of the local commit;
23//! the PDS write that follows is idempotent (atproto `putRecord` is
24//! last-writer-wins on the record `rkey`), so a crashed promote that already
25//! committed locally simply re-runs and advances the pointer on retry.
26//!
27//! # Eventual consistency, not atomicity
28//!
29//! Promote spans two stores: the local git repo and the atproto PDS. We do
30//! **not** pretend this is atomic. The local commit happens first and is
31//! durable; the PDS record update happens second. If the PDS write fails after
32//! the local commit succeeds:
33//!
34//! - The content is committed locally and reachable via the git ref.
35//! - The atproto pointer is **stale** — it still points at the previous head.
36//! - The next successful promote advances the pointer to the latest local
37//! head, skipping the stale intermediate. Because git commits are
38//! content-addressed and parent-chained, no commit is lost: the stale
39//! pointer simply lags until a later promote catches up.
40//!
41//! This is the honest treatment. A two-phase-commit across git + atproto would
42//! require a PDS that supports prepare/commit, which atproto does not; the
43//! pointer-record pattern is the standard atproto eventual-consistency
44//! primitive (it is how Bluesky itself advances collection pointers).
45//!
46//! # No new RPC
47//!
48//! Promote reuses the existing `stageAll` + `commit` worktree verbs from
49//! `registry.capnp`. The PDS record write is a plain HTTPS `putRecord` call,
50//! not a hyprstream RPC — the atproto substrate (#355/#410) owns that client.
51
52use std::collections::HashMap;
53use std::sync::Arc;
54
55use parking_lot::Mutex;
56use tracing::{info, warn};
57
58use hyprstream_rpc_std::registry_client::{CommitWithAuthorRequest, WorktreeClient};
59
60/// An error from the promote saga.
61#[derive(Debug)]
62pub enum PromoteError {
63 /// Another node currently holds the promote lease for this layer.
64 LeaseHeld(String),
65 /// The local stage/commit step failed.
66 LocalCommit(String),
67 /// The atproto pointer-record update failed. The local commit already
68 /// succeeded — the pointer is stale and will be advanced by the next
69 /// successful promote. See the module-level eventual-consistency note.
70 PointerStale(String),
71}
72
73impl std::fmt::Display for PromoteError {
74 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
75 match self {
76 Self::LeaseHeld(s) => write!(f, "promote lease held by another node: {s}"),
77 Self::LocalCommit(s) => write!(f, "local commit failed: {s}"),
78 Self::PointerStale(s) => {
79 write!(
80 f,
81 "local commit ok but atproto pointer update failed (stale): {s}"
82 )
83 }
84 }
85 }
86}
87
88impl std::error::Error for PromoteError {}
89
90/// Outcome of a successful [`promote`].
91#[derive(Clone, Debug)]
92pub struct PromoteOutcome {
93 /// OID of the freshly committed snapshot (deterministic across nodes).
94 pub commit_oid: String,
95 /// Whether the atproto pointer record was advanced in this run. Always
96 /// `Ok(())` on a clean promote; consult [`PromoteError::PointerStale`] for
97 /// the failure case where the pointer lags.
98 pub pointer_advanced: bool,
99}
100
101/// A held per-layer promote lease. Dropping it releases the layer for other
102/// nodes to promote.
103///
104/// This is an in-process token; the distributed single-writer invariant
105/// (Shapiro) is enforced at the registry/PDS layer by the pointer-record
106/// version check. The in-process lease prevents the common case of two
107/// concurrent promotes from the *same* node racing on the same worktree.
108pub struct PromoteLease {
109 key: String,
110 table: Arc<PromoteLeaseTable>,
111}
112
113impl std::fmt::Debug for PromoteLease {
114 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
115 f.debug_struct("PromoteLease")
116 .field("key", &self.key)
117 .finish()
118 }
119}
120
121impl Drop for PromoteLease {
122 fn drop(&mut self) {
123 self.table.0.lock().remove(&self.key);
124 }
125}
126
127/// Per-process registry of held promote leases, keyed by `{repo}:{worktree}`.
128#[derive(Default)]
129pub struct PromoteLeaseTable(Mutex<HashMap<String, ()>>);
130
131impl PromoteLeaseTable {
132 /// Create an empty lease table.
133 pub fn new() -> Self {
134 Self::default()
135 }
136
137 /// Try to acquire the lease for `key`. Returns `Err(LeaseHeld)` if another
138 /// promoter already holds it.
139 pub fn acquire(self: &Arc<Self>, key: &str) -> Result<PromoteLease, PromoteError> {
140 let mut guard = self.0.lock();
141 if guard.contains_key(key) {
142 return Err(PromoteError::LeaseHeld(key.to_owned()));
143 }
144 guard.insert(key.to_owned(), ());
145 Ok(PromoteLease {
146 key: key.to_owned(),
147 table: Arc::clone(self),
148 })
149 }
150}
151
152/// The node identity used to author the promote commit and the atproto record.
153#[derive(Clone, Debug)]
154pub struct PromoteAuthor {
155 /// atproto / git author name.
156 pub name: String,
157 /// atproto / git author email (or PDS account DID).
158 pub email: String,
159}
160
161/// Advance the atproto pointer record for `repo`/`worktree` to `commit_oid`.
162///
163/// This is the PDS-side of the saga. It is a `putRecord` to the model-pointer
164/// collection. The atproto substrate (#355/#410) owns the actual HTTPS client;
165/// until that lands, this is a stub that logs and returns `Ok`. The signature
166/// is fixed now so the promote path does not change shape when the real client
167/// is wired in — only the body of this function changes.
168///
169/// **Idempotent:** `putRecord` is last-writer-wins on the record `rkey`, so a
170/// retry after a crash simply overwrites with the same (or newer) OID.
171async fn advance_pointer(
172 _repo: &str,
173 _worktree: &str,
174 commit_oid: &str,
175 _author: &PromoteAuthor,
176) -> Result<(), String> {
177 // TODO(atproto, #355/#410): replace with a real PDS putRecord call to the
178 // model-pointer collection. The record shape is:
179 // { "$type": "ai.hyprstream.modelPointer", "head": <commit_oid>, ... }
180 // Until the atproto substrate client lands, log and succeed — the local
181 // commit is durable and the pointer is advisory.
182 info!(
183 commit_oid,
184 "promote: atproto pointer update stubbed (substrate #355/#410 pending); local commit is durable"
185 );
186 Ok(())
187}
188
189/// Run the promote saga for a single worktree.
190///
191/// `repo`/`worktree` identify the layer; `wt` is the worktree-scoped registry
192/// client (curried `repo(id).worktree(name)`) whose `stage_all` / `commit`
193/// verbs perform the local snapshot; `author` is the commit + atproto-record
194/// identity; `lease_table` enforces single-writer-per-layer for this process.
195///
196/// # Determinism
197///
198/// Two nodes promoting byte-identical upper-layer content produce identical
199/// commit OIDs, because `stageAll` + `commit` reduce to `git add -A` +
200/// `git commit` over a deterministic index, and git commit OIDs are a pure
201/// function of (tree, parents, author, committer, message). The
202/// [`PromoteAuthor`] must therefore be a stable identity, not a per-call
203/// ephemeral — the caller is responsible for threading the same author across
204/// competing promotes (the registry service derives it from the verified
205/// `Subject`).
206///
207/// # Errors
208///
209/// - [`PromoteError::LeaseHeld`]: another promoter on this node holds the
210/// layer's lease.
211/// - [`PromoteError::LocalCommit`]: the stage/commit RPC failed; nothing was
212/// committed.
213/// - [`PromoteError::PointerStale`]: the local commit succeeded but the PDS
214/// write failed. The content is committed; the next promote advances the
215/// pointer. The caller should surface this as a warning, not a hard failure.
216pub async fn promote(
217 repo: &str,
218 worktree: &str,
219 wt: &WorktreeClient,
220 author: &PromoteAuthor,
221 lease_table: &Arc<PromoteLeaseTable>,
222) -> Result<PromoteOutcome, PromoteError> {
223 let lease_key = format!("{repo}/{worktree}");
224 let _lease = lease_table.acquire(&lease_key)?;
225
226 // Phase 1: local snapshot (deterministic). stageAll + commit.
227 wt.stage_all()
228 .await
229 .map_err(|e| PromoteError::LocalCommit(format!("stageAll: {e}")))?;
230 let commit_oid = wt
231 .commit_with_author(&CommitWithAuthorRequest {
232 message: commit_message(repo, worktree),
233 author_name: author.name.clone(),
234 author_email: author.email.clone(),
235 })
236 .await
237 .map_err(|e| PromoteError::LocalCommit(format!("commit: {e}")))?;
238
239 info!(
240 repo,
241 worktree, commit_oid, "promote: local snapshot committed"
242 );
243
244 // Phase 2: advance the atproto pointer (eventual consistency). A failure
245 // here does NOT roll back the local commit — see the module-level note.
246 let pointer_advanced = match advance_pointer(repo, worktree, &commit_oid, author).await {
247 Ok(()) => true,
248 Err(e) => {
249 warn!(
250 repo, worktree, commit_oid, error = %e,
251 "promote: atproto pointer update failed; content committed, pointer stale"
252 );
253 return Err(PromoteError::PointerStale(e));
254 }
255 };
256
257 Ok(PromoteOutcome {
258 commit_oid,
259 pointer_advanced,
260 })
261}
262
263/// Build a deterministic, human-readable commit message for a promote.
264///
265/// The message is stable for a given (repo, worktree) pair so that two nodes
266/// promoting the same content produce identical commit metadata (and therefore
267/// identical OIDs, modulo timestamp — git folds the committer timestamp into
268/// the OID, so true cross-node determinism requires the registry service to
269/// pin the timestamp, which it does via `commitWithAuthor`). The *message* is
270/// deterministic regardless.
271fn commit_message(repo: &str, worktree: &str) -> String {
272 format!("promote: {repo}/{worktree}\n\nSnapshot node-local upper layer into registry.\n\nGenerated by hyprstream promote (#394).")
273}
274
275#[cfg(test)]
276#[allow(clippy::unwrap_used)]
277mod tests {
278 use super::*;
279
280 #[test]
281 fn lease_acquire_and_release() {
282 let table = Arc::new(PromoteLeaseTable::new());
283 let lease = table.acquire("repo/wt").unwrap();
284 // Second acquire on the same key fails.
285 assert!(matches!(
286 table.acquire("repo/wt"),
287 Err(PromoteError::LeaseHeld(_))
288 ));
289 // Different key is fine.
290 let _lease2 = table.acquire("repo/other").unwrap();
291 // Dropping the first releases it.
292 drop(lease);
293 let _lease3 = table.acquire("repo/wt").unwrap();
294 }
295
296 #[test]
297 fn commit_message_is_stable() {
298 let a = commit_message("foo", "main");
299 let b = commit_message("foo", "main");
300 assert_eq!(a, b);
301 assert!(a.contains("foo/main"));
302 assert!(a.contains("#394"));
303 }
304
305 #[tokio::test]
306 async fn advance_pointer_stub_succeeds() {
307 // Until the atproto substrate lands, the stub always succeeds — this
308 // test pins that contract so wiring the real client is a body-only
309 // change.
310 let author = PromoteAuthor {
311 name: "n".into(),
312 email: "e".into(),
313 };
314 advance_pointer("r", "w", "deadbeef", &author)
315 .await
316 .unwrap();
317 }
318}