OXYGENHUB
# 598009a75f6c oxygen / crates / oxy-core / src / repo / sync.rs
62.6 KiB · Rust · last changed Render a file that is one chain of lines without contracting it 1 month ago source blame history raw
1 
//! Serving and talking to remotes (spec §10.2, §16).
2
3 
use super::*;
4
5 
/// What a push did, for hosts (hub spec §6.12).
6 
#[derive(Clone, Debug, Default)]
7 
pub struct PushReport {
8 
    pub results: Vec<RefResult>,
9 
    /// Accepted reference updates, in request order.
10 
    pub updated: Vec<RefUpdated>,
11 
    /// Changes this push stored that were not already present.
12 
    pub imported: Vec<ChangeHash>,
13 
}
14
15 
#[derive(Clone, Debug)]
16 
pub struct RefUpdated {
17 
    pub name: String,
18 
    pub old_state: ObjectRef,
19 
    pub new_state: ObjectRef,
20 
    pub heads: Vec<ChangeHash>,
21 
}
22
23 
/// What a fetch brought in.
24 
#[derive(Debug, Clone, PartialEq, Eq, Default)]
25 
pub struct FetchReport {
26 
    /// Bookmark name, its heads, and how many changes were new.
27 
    pub refs: Vec<(String, Vec<ChangeHash>, usize)>,
28 
    /// Tags adopted from the remote.
29 
    pub new_tags: usize,
30 
    /// The remote has never presented a policy, so nothing was verified
31 
    /// against one (spec §14.5: warn loudly).
32 
    pub unverified: bool,
33 
}
34
35 
#[derive(Debug, Clone, PartialEq, Eq)]
36 
pub struct PullReport {
37 
    pub heads: Vec<ChangeHash>,
38 
    pub changed: bool,
39 
    pub checked_out: bool,
40 
}
41
42 
impl Repo {
43 
    // ------------------------------------------------------------ serving (spec §16)
44
45 
    fn ref_attest_path(&self, bookmark: &str) -> PathBuf {
46 
        self.oxy.join("attest").join(name_file(bookmark))
47 
    }
48
49 
    /// The latest reference attestation stored for a bookmark.
50 
    pub fn latest_ref_attest(&self, bookmark: &str) -> Result<Option<(ObjectRef, SignedAttest)>> {
51 
        match fs::read_to_string(self.ref_attest_path(bookmark)) {
52 
            Ok(h) => {
53 
                let r = ObjectRef::from_hex(h.trim())
54 
                    .ok_or_else(|| RepoError::Msg("corrupt attestation pointer".into()))?;
55 
                Ok(Some((
56 
                    r,
57 
                    SignedAttest {
58 
                        attest: self.store.get_attest(&r)?,
59 
                        sigs: self.store.signatures(&r)?,
60 
                    },
61 
                )))
62 
            }
63 
            Err(e) if e.kind() == std::io::ErrorKind::NotFound => Ok(None),
64 
            Err(e) => Err(e.into()),
65 
        }
66 
    }
67
68 
    fn set_ref_attest(&self, bookmark: &str, r: &ObjectRef) -> Result<()> {
69 
        fs::create_dir_all(self.oxy.join("attest"))?;
70 
        write_atomic(&self.ref_attest_path(bookmark), r.to_hex().as_bytes())
71 
    }
72
73 
    pub fn remote_refs(&self) -> Result<RefsResponse> {
74 
        let view = self.view()?;
75 
        let mut out = Vec::new();
76 
        for (name, state) in &view.bookmarks {
77 
            let latest = self.latest_ref_attest(name)?.map(|(_, a)| a);
78 
            let last_serial = latest.as_ref().and_then(|a| match a.attest.body {
79 
                AttestBody::Ref { serial, .. } => Some(serial),
80 
                _ => None,
81 
            });
82 
            let attestation = latest.filter(|a| matches!(&a.attest.body, AttestBody::Ref { new_state, .. } if new_state == state));
83 
            out.push(RemoteRef {
84 
                name: name.clone(),
85 
                state: *state,
86 
                heads: self.store.get_state(state)?.heads,
87 
                attestation,
88 
                last_serial,
89 
            });
90 
        }
91 
        let policy = self.current_policy()?.map(|(_, sp)| sp);
92 
        let history = self
93 
            .policy_history()?
94 
            .into_iter()
95 
            .filter(|sp| {
96 
                policy
97 
                    .as_ref()
98 
                    .is_some_and(|p| sp.policy.serial < p.policy.serial)
99 
            })
100 
            .collect();
101 
        Ok(RefsResponse {
102 
            refs: out,
103 
            policy,
104 
            tags: self.tag_refs()?,
105 
            history,
106 
        })
107 
    }
108
109 
    /// Every change reachable from `heads` that is in the store.
110 
    fn closure_in_store(&self, heads: &[ChangeHash]) -> Result<BTreeSet<ChangeHash>> {
111 
        let mut seen = BTreeSet::new();
112 
        let mut stack: Vec<ChangeHash> = heads.to_vec();
113 
        while let Some(h) = stack.pop() {
114 
            if seen.contains(&h) || !self.store.has(&h) {
115 
                continue;
116 
            }
117 
            seen.insert(h);
118 
            stack.extend(self.store.get_change_meta(&h)?.deps);
119 
        }
120 
        Ok(seen)
121 
    }
122
123 
    /// The changes within `depth` dependency steps of `heads` (spec §17),
124 
    /// nearest first; depth 1 is the heads themselves.
125 
    pub fn shallow_changes(&self, heads: &[ChangeHash], depth: u32) -> Result<Vec<ChangeHash>> {
126 
        let mut out = Vec::new();
127 
        let mut seen: BTreeSet<ChangeHash> = BTreeSet::new();
128 
        let mut layer: Vec<ChangeHash> = heads.to_vec();
129 
        for _ in 0..depth.max(1) {
130 
            let mut next = Vec::new();
131 
            for h in layer {
132 
                if !seen.insert(h) || !self.store.has(&h) {
133 
                    continue;
134 
                }
135 
                let c = self.store.get_change(&h)?;
136 
                next.extend(c.deps.iter().copied());
137 
                out.push(h);
138 
            }
139 
            if next.is_empty() {
140 
                break;
141 
            }
142 
            layer = next;
143 
        }
144 
        out.reverse();
145 
        Ok(out)
146 
    }
147
148 
    fn shallow_path(&self) -> PathBuf {
149 
        self.oxy.join("shallow")
150 
    }
151
152 
    /// The shallow boundary: dependencies this repository does not hold (spec §17).
153 
    pub fn boundary(&self) -> BTreeSet<ChangeHash> {
154 
        fs::read_to_string(self.shallow_path())
155 
            .map(|t| t.lines().filter_map(ObjectRef::from_hex).collect())
156 
            .unwrap_or_default()
157 
    }
158
159 
    pub fn is_shallow(&self) -> bool {
160 
        !self.boundary().is_empty()
161 
    }
162
163 
    fn write_boundary(&self, boundary: &BTreeSet<ChangeHash>) -> Result<()> {
164 
        if boundary.is_empty() {
165 
            let _ = fs::remove_file(self.shallow_path());
166 
            return Ok(());
167 
        }
168 
        let text: String = boundary
169 
            .iter()
170 
            .map(|h| format!("{}\n", h.to_hex()))
171 
            .collect();
172 
        write_atomic(&self.shallow_path(), text.as_bytes())
173 
    }
174
175 
    /// Recompute the boundary from what is stored: every dependency of a
176 
    /// stored change that is not itself stored.
177 
    fn refresh_boundary(&self, imported: &[ChangeHash]) -> Result<()> {
178 
        let mut boundary = self.boundary();
179 
        boundary.retain(|h| !self.store.has(h));
180 
        for h in imported {
181 
            for d in self.store.get_change_meta(h)?.deps {
182 
                if !self.store.has(&d) {
183 
                    boundary.insert(d);
184 
                }
185 
            }
186 
        }
187 
        self.write_boundary(&boundary)
188 
    }
189
190 
    /// Fetch `depth` more levels of history below the shallow boundary.
191 
    pub fn deepen(&self, remote_name: &str, depth: u32) -> Result<usize> {
192 
        let boundary = self.boundary();
193 
        if boundary.is_empty() {
194 
            return Ok(0);
195 
        }
196 
        let remote = self.open_named_remote(remote_name)?;
197 
        let wanted = remote.shallow(&boundary.iter().copied().collect::<Vec<_>>(), depth)?;
198 
        let bundle = remote.fetch(&wanted, self.config.max_blob)?;
199 
        let imported = self.import_bundle_shallow(&bundle, false)?;
200 
        if self.config.max_blob.is_some() {
201 
            self.register_missing_blobs(&imported, remote_name)?;
202 
        }
203 
        self.refresh_boundary(&imported)?;
204 
        Ok(imported.len())
205 
    }
206
207 
    /// `closure(want) \ closure(have)`, dependencies first (spec §16.2).
208 
    pub fn negotiate(&self, have: &[ChangeHash], want: &[ChangeHash]) -> Result<Vec<ChangeHash>> {
209 
        let have = self.closure_in_store(have)?;
210 
        // In a shallow repository the walk stops at the boundary, whose
211 
        // changes the remote is assumed to hold.
212 
        let boundary = self.boundary();
213 
        let mut out = Vec::new();
214 
        let mut done: BTreeSet<ChangeHash> = have.clone();
215 
        done.extend(boundary.iter().copied());
216 
        // Iterative post-order DFS.
217 
        let mut stack: Vec<(ChangeHash, bool)> = want.iter().rev().map(|h| (*h, false)).collect();
218 
        while let Some((h, expanded)) = stack.pop() {
219 
            if done.contains(&h) {
220 
                continue;
221 
            }
222 
            if !self.store.has(&h) {
223 
                return fail(format!("change {} is not in this repository", h.short(12)));
224 
            }
225 
            if expanded {
226 
                done.insert(h);
227 
                out.push(h);
228 
                continue;
229 
            }
230 
            stack.push((h, true));
231 
            for d in self.store.get_change_meta(&h)?.deps {
232 
                if !done.contains(&d) {
233 
                    stack.push((d, false));
234 
                }
235 
            }
236 
        }
237 
        Ok(out)
238 
    }
239
240 
    /// Bundle changes (in the given dependency order) with their signatures,
241 
    /// seals, identities, blobs, chunks.
242 
    pub fn bundle_for(&self, changes: &[ChangeHash]) -> Result<Bundle> {
243 
        self.bundle_for_filtered(changes, None)
244 
    }
245
246 
    /// Objects by reference for the `objects` endpoint; a blob brings its chunks.
247 
    pub fn objects_for(&self, refs: &[ObjectRef]) -> Result<Vec<(ObjectType, Vec<u8>)>> {
248 
        let mut out = Vec::new();
249 
        for r in refs {
250 
            let (ty, body) = match self.store.get(r) {
251 
                Ok(x) => x,
252 
                Err(StoreError::NotFound(_)) => continue,
253 
                Err(e) => return Err(e.into()),
254 
            };
255 
            if ty == ObjectType::Blob {
256 
                for c in Blob::decode(&body)?.chunks {
257 
                    if let Ok((cty, cb)) = self.store.get(&c) {
258 
                        out.push((cty, cb));
259 
                    }
260 
                }
261 
            }
262 
            out.push((ty, body));
263 
        }
264 
        Ok(out)
265 
    }
266
267 
    /// Like `bundle_for`, leaving out blobs larger than `max_blob` bytes
268 
    /// (and their chunks) so the receiver fetches them lazily (spec §13.5).
269 
    pub fn bundle_for_filtered(
270 
        &self,
271 
        changes: &[ChangeHash],
272 
        max_blob: Option<u64>,
273 
    ) -> Result<Bundle> {
274 
        let mut bundle = Bundle::default();
275 
        let mut objects: BTreeSet<ObjectRef> = BTreeSet::new();
276 
        let mut seals: BTreeSet<ObjectRef> = BTreeSet::new();
277 
        let add_object = |r: &ObjectRef, objects: &mut BTreeSet<ObjectRef>| {
278 
            if !r.is_zero() && self.store.has(r) {
279 
                objects.insert(*r);
280 
            }
281 
        };
282 
        for h in changes {
283 
            let c = self.store.get_change(h)?;
284 
            let sigs = self.store.signatures(h)?;
285 
            add_object(&c.author, &mut objects);
286 
            for s in &sigs {
287 
                add_object(&s.key, &mut objects);
288 
            }
289 
            for e in &c.edits {
290 
                if let Edit::Replace { old, new, .. } = e {
291 
                    for b in [old, new].into_iter().flatten() {
292 
                        if self.store.has(b) {
293 
                            if let Ok(blob) =
294 
                                Blob::decode(&self.store.get_typed(b, ObjectType::Blob)?)
295 
                            {
296 
                                if max_blob.is_some_and(|m| blob.length > m) {
297 
                                    continue;
298 
                                }
299 
                                objects.insert(*b);
300 
                                objects.extend(blob.chunks.iter().copied());
301 
                            }
302 
                        }
303 
                    }
304 
                }
305 
            }
306 
            for s in self.store.seals_for(h)? {
307 
                seals.insert(s);
308 
            }
309 
            bundle.changes.push((c, sigs));
310 
            bundle.hashes.push(*h);
311 
        }
312 
        for r in seals {
313 
            let attest = self.store.get_attest(&r)?;
314 
            let sigs = self.store.signatures(&r)?;
315 
            for s in &sigs {
316 
                add_object(&s.key, &mut objects);
317 
            }
318 
            bundle.attests.push(SignedAttest { attest, sigs });
319 
        }
320 
        for r in objects {
321 
            let (ty, body) = self.store.get(&r)?;
322 
            bundle.objects.push((ty, body));
323 
        }
324 
        Ok(bundle)
325 
    }
326
327 
    /// Store a bundle's contents. With `strict`, every change must
328 
    /// authenticate (signature or seal by its author or a delegate).
329 
    pub fn import_bundle(&self, bundle: &Bundle, strict: bool) -> Result<Vec<ChangeHash>> {
330 
        self.import_bundle_inner(bundle, strict, false)
331 
    }
332
333 
    /// Like `import_bundle`, accepting changes whose dependencies are absent
334 
    /// (they join the shallow boundary).
335 
    pub fn import_bundle_shallow(&self, bundle: &Bundle, strict: bool) -> Result<Vec<ChangeHash>> {
336 
        self.import_bundle_inner(bundle, strict, true)
337 
    }
338
339 
    fn import_bundle_inner(
340 
        &self,
341 
        bundle: &Bundle,
342 
        strict: bool,
343 
        shallow: bool,
344 
    ) -> Result<Vec<ChangeHash>> {
345 
        let batch = self.store.begin_batch()?;
346 
        let result = self.import_bundle_batched(bundle, strict, shallow);
347 
        batch.finish()?;
348 
        result
349 
    }
350
351 
    fn import_bundle_batched(
352 
        &self,
353 
        bundle: &Bundle,
354 
        strict: bool,
355 
        shallow: bool,
356 
    ) -> Result<Vec<ChangeHash>> {
357 
        for (ty, body) in &bundle.objects {
358 
            match ty {
359 
                ObjectType::Chunk
360 
                | ObjectType::Blob
361 
                | ObjectType::Identity
362 
                | ObjectType::State
363 
                | ObjectType::Checkpoint => {
364 
                    self.store.put(*ty, body)?;
365 
                }
366 
                other => return fail(format!("bundle may not carry {} objects", other.name())),
367 
            }
368 
        }
369 
        for sa in &bundle.attests {
370 
            let r = self.store.put_attest(&sa.attest)?;
371 
            for sig in &sa.sigs {
372 
                self.store.put_signature(&r, sig)?;
373 
            }
374 
            if let AttestBody::Seal { hashes } = &sa.attest.body {
375 
                for h in hashes {
376 
                    self.store.index_seal(h, &r)?;
377 
                }
378 
            }
379 
        }
380 
        // Each change's hash: from the bundle when its maker knew it, else
381 
        // worked out once (for a change adding a whole tree, hashing is
382 
        // chunking all its text).
383 
        let hashes: Vec<ChangeHash> = if bundle.hashes.len() == bundle.changes.len() {
384 
            bundle.hashes.clone()
385 
        } else {
386 
            bundle.changes.iter().map(|(c, _)| c.hash()).collect()
387 
        };
388 
        let incoming: BTreeSet<ChangeHash> = hashes.iter().copied().collect();
389 
        let boundary = self.boundary();
390 
        let mut imported = Vec::new();
391 
        for ((c, sigs), h) in bundle.changes.iter().zip(hashes) {
392 
            for d in &c.deps {
393 
                if !self.store.has(d) && !incoming.contains(d) && !shallow && !boundary.contains(d)
394 
                {
395 
                    return fail(format!(
396 
                        "change {} depends on {}, which is neither stored nor in the bundle",
397 
                        h.short(12),
398 
                        d.short(12)
399 
                    ));
400 
                }
401 
            }
402 
            let stored = self.store.put_change(c)?;
403 
            if stored != h {
404 
                return fail(format!(
405 
                    "change {} is not the change the bundle names",
406 
                    h.short(12)
407 
                ));
408 
            }
409 
            for sig in sigs {
410 
                self.store.put_signature(&h, sig)?;
411 
            }
412 
            imported.push(h);
413 
        }
414 
        if strict {
415 
            for h in &imported {
416 
                if !matches!(self.authenticate_change(h)?, SignatureStatus::Valid { .. }) {
417 
                    return fail(format!(
418 
                        "change {} is not authenticated by its author",
419 
                        h.short(12)
420 
                    ));
421 
                }
422 
            }
423 
        }
424 
        Ok(imported)
425 
    }
426
427 
    /// Verify a reference attestation against an update it claims to describe.
428 
    /// `allow_equal` lets a client re-read the attestation it already has; a
429 
    /// server receiving a push requires a strictly greater serial.
430 
    /// A reference attestation signed by a delegate of an identity the
431 
    /// rule lists is authorized as that identity (spec §14.5): the identity
432 
    /// named the delegate, and the policy names the identity. Revoked keys
433 
    /// authorize nothing either way.
434 
    pub(crate) fn delegate_authorized(
435 
        &self,
436 
        p: &crate::policy::Policy,
437 
        signer: &KeyId,
438 
        reference: &str,
439 
    ) -> bool {
440 
        if p.is_revoked(signer) {
441 
            return false;
442 
        }
443 
        let Some(rule) = p.rule_for(reference) else {
444 
            return false;
445 
        };
446 
        rule.keys.iter().any(|k| {
447 
            !p.is_revoked(k)
448 
                && p.identity(k)
449 
                    .cloned()
450 
                    .or_else(|| self.store.get_identity(k).ok())
451 
                    .is_some_and(|id| id.delegates.contains(signer))
452 
        })
453 
    }
454
455 
    fn check_ref_attest(
456 
        &self,
457 
        sa: &SignedAttest,
458 
        name: &str,
459 
        old_state: &ObjectRef,
460 
        new_state: &ObjectRef,
461 
        last_serial: Option<u64>,
462 
        allow_equal: bool,
463 
    ) -> std::result::Result<u64, String> {
464 
        let AttestBody::Ref {
465 
            name: n,
466 
            old_state: o,
467 
            new_state: nw,
468 
            serial,
469 
        } = &sa.attest.body
470 
        else {
471 
            return Err("attestation is not a ref attestation".into());
472 
        };
473 
        if n != name || o != old_state || nw != new_state {
474 
            return Err("attestation does not describe this update".into());
475 
        }
476 
        if sa.attest.repo != self.id().map_err(|e| e.to_string())? {
477 
            return Err("attestation is for a different repository".into());
478 
        }
479 
        if let Some(last) = last_serial {
480 
            if *serial < last || (*serial == last && !allow_equal) {
481 
                return Err(format!(
482 
                    "attestation serial {serial} is not greater than the last seen {last}"
483 
                ));
484 
            }
485 
        }
486 
        let r = sa.attest.hash();
487 
        let sig = sa.sigs.first().ok_or("attestation carries no signature")?;
488 
        let id = self
489 
            .store
490 
            .get_identity(&sig.key)
491 
            .map_err(|_| format!("unknown key {}", sig.key.short(12)))?;
492 
        verify_signature(&id, sig, Domain::Attest, &r).map_err(|e| e.to_string())?;
493 
        Ok(*serial)
494 
    }
495
496 
    /// Accept a push (spec §16.4). Without a trust policy every repository
497 
    /// is unverified, so unsigned changes and unattested updates are accepted;
498 
    /// attestations that are present must still be valid. With a policy,
499 
    /// every change and update is checked against it. A newer policy in the
500 
    /// push is applied first when it is signed by the current roots.
501 
    pub fn receive_push(
502 
        &self,
503 
        bundle: Bundle,
504 
        updates: Vec<RefUpdate>,
505 
        policy: Option<SignedPolicy>,
506 
        tags: Vec<crate::protocol::TagRef>,
507 
    ) -> Result<Vec<RefResult>> {
508 
        Ok(self
509 
            .receive_push_report(bundle, updates, policy, tags)?
510 
            .results)
511 
    }
512
513 
    /// `receive_push` with what a host wants to log: each accepted
514 
    /// reference's old and new state and heads, and the changes this push
515 
    /// stored (hub spec §6.12).
516 
    pub fn receive_push_report(
517 
        &self,
518 
        bundle: Bundle,
519 
        updates: Vec<RefUpdate>,
520 
        policy: Option<SignedPolicy>,
521 
        tags: Vec<crate::protocol::TagRef>,
522 
    ) -> Result<PushReport> {
523 
        let mut report = PushReport::default();
524 
        let results = &mut report.results;
525 
        if let Some(sp) = policy {
526 
            match self.adopt_policy_chain(&bundle.policies, &sp, "push received") {
527 
                Ok(()) => {
528 
                    results.push(RefResult {
529 
                        name: "policy".into(),
530 
                        ok: true,
531 
                        reason: format!("serial {}", sp.policy.serial),
532 
                    });
533 
                }
534 
                Err(e) => {
535 
                    results.push(RefResult {
536 
                        name: "policy".into(),
537 
                        ok: false,
538 
                        reason: e,
539 
                    });
540 
                    for u in updates {
541 
                        results.push(RefResult {
542 
                            name: u.name,
543 
                            ok: false,
544 
                            reason: "policy update was rejected".into(),
545 
                        });
546 
                    }
547 
                    return Ok(report);
548 
                }
549 
            }
550 
        }
551 
        let policy = self.current_policy()?.map(|(_, sp)| sp.policy);
552 
        match self.import_bundle(&bundle, policy.is_some()) {
553 
            Ok(imported) => report.imported = imported,
554 
            Err(e) => {
555 
                for u in updates {
556 
                    results.push(RefResult {
557 
                        name: u.name,
558 
                        ok: false,
559 
                        reason: e.to_string(),
560 
                    });
561 
                }
562 
                return Ok(report);
563 
            }
564 
        }
565 
        let (op_ref, op) = self.head_op()?;
566 
        let mut view = op.view.clone();
567 
        let mut names = Vec::new();
568 
        for u in updates {
569 
            let outcome = self.apply_update(&mut view, &u, policy.as_ref());
570 
            let (ok, reason) = match outcome {
571 
                Ok(()) => (true, String::new()),
572 
                Err(e) => (false, e),
573 
            };
574 
            if ok {
575 
                names.push(u.name.clone());
576 
                let heads = self
577 
                    .store
578 
                    .get_state(&u.new_state)
579 
                    .map(|s| s.heads)
580 
                    .unwrap_or_default();
581 
                report.updated.push(RefUpdated {
582 
                    name: u.name.clone(),
583 
                    old_state: u.old_state,
584 
                    new_state: u.new_state,
585 
                    heads,
586 
                });
587 
            }
588 
            results.push(RefResult {
589 
                name: u.name,
590 
                ok,
591 
                reason,
592 
            });
593 
        }
594 
        for t in &tags {
595 
            let name = format!("tags/{}", t.name);
596 
            match self.adopt_tag(&mut view, t, policy.as_ref()) {
597 
                Ok(()) => {
598 
                    names.push(name.clone());
599 
                    results.push(RefResult {
600 
                        name,
601 
                        ok: true,
602 
                        reason: String::new(),
603 
                    });
604 
                }
605 
                Err(e) => results.push(RefResult {
606 
                    name,
607 
                    ok: false,
608 
                    reason: e,
609 
                }),
610 
            }
611 
        }
612 
        if !names.is_empty() {
613 
            self.record_op(
614 
                &[op_ref],
615 
                &format!("push received: {}", names.join(" ")),
616 
                view,
617 
            )?;
618 
        }
619 
        Ok(report)
620 
    }
621
622 
    /// A deletion (spec §16.4): `new_state` is zero. The bookmark must exist
623 
    /// at `old_state`, is never the repository's own bookmark (its default),
624 
    /// and under a policy needs an attestation by a key that may update it.
625 
    /// The deletion's attestation stays the bookmark's latest, so an older
626 
    /// one cannot be replayed to bring it back.
627 
    fn apply_deletion(
628 
        &self,
629 
        view: &mut View,
630 
        u: &RefUpdate,
631 
        policy: Option<&crate::policy::Policy>,
632 
    ) -> std::result::Result<(), String> {
633 
        let Some(current) = view.bookmarks.get(&u.name).copied() else {
634 
            return Err(format!("no bookmark {:?} to delete", u.name));
635 
        };
636 
        if current != u.old_state {
637 
            return Err("stale: the remote bookmark has moved; pull first".into());
638 
        }
639 
        if u.name == self.config.bookmark {
640 
            return Err(format!(
641 
                "{:?} is this repository's default bookmark and cannot be deleted",
642 
                u.name
643 
            ));
644 
        }
645 
        if let Some(p) = policy {
646 
            let Some(sa) = &u.attestation else {
647 
                return Err(format!(
648 
                    "deleting {:?} requires a signed reference attestation under this repository's policy",
649 
                    u.name
650 
                ));
651 
            };
652 
            let signer = sa
653 
                .sigs
654 
                .first()
655 
                .map(|s| s.key)
656 
                .ok_or("attestation carries no signature")?;
657 
            if !p.authorizes(&signer, &u.name) && !self.delegate_authorized(p, &signer, &u.name) {
658 
                return Err(format!(
659 
                    "key {} may not delete {:?} under this repository's policy",
660 
                    signer.short(12),
661 
                    u.name
662 
                ));
663 
            }
664 
        }
665 
        if let Some(sa) = &u.attestation {
666 
            let last = self
667 
                .latest_ref_attest(&u.name)
668 
                .map_err(|e| e.to_string())?
669 
                .and_then(|(_, a)| match a.attest.body {
670 
                    AttestBody::Ref { serial, .. } => Some(serial),
671 
                    _ => None,
672 
                });
673 
            self.check_ref_attest(sa, &u.name, &u.old_state, &u.new_state, last, false)?;
674 
            let r = self
675 
                .store
676 
                .put_attest(&sa.attest)
677 
                .map_err(|e| e.to_string())?;
678 
            for sig in &sa.sigs {
679 
                self.store
680 
                    .put_signature(&r, sig)
681 
                    .map_err(|e| e.to_string())?;
682 
            }
683 
            self.set_ref_attest(&u.name, &r)
684 
                .map_err(|e| e.to_string())?;
685 
        }
686 
        view.bookmarks.remove(&u.name);
687 
        Ok(())
688 
    }
689
690 
    fn apply_update(
691 
        &self,
692 
        view: &mut View,
693 
        u: &RefUpdate,
694 
        policy: Option<&crate::policy::Policy>,
695 
    ) -> std::result::Result<(), String> {
696 
        if u.name == "policy" {
697 
            return Err(
698 
                "the policy reference is updated by sending a policy, not a bookmark update".into(),
699 
            );
700 
        }
701 
        let empty = self
702 
            .store
703 
            .put_state(&StateObject::new(vec![]))
704 
            .map_err(|e| e.to_string())?;
705 
        if u.new_state.is_zero() {
706 
            return self.apply_deletion(view, u, policy);
707 
        }
708 
        let current = view.bookmarks.get(&u.name).copied().unwrap_or(empty);
709 
        if current != u.old_state {
710 
            return Err("stale: the remote bookmark has moved; pull first".into());
711 
        }
712 
        let new_state = self
713 
            .store
714 
            .get_state(&u.new_state)
715 
            .map_err(|_| "new state object is missing".to_string())?;
716 
        for h in &new_state.heads {
717 
            if !self.store.has(h) {
718 
                return Err(format!("head {} is missing", h.short(12)));
719 
            }
720 
        }
721 
        if !u.force {
722 
            let old_heads = self
723 
                .store
724 
                .get_state(&current)
725 
                .map_err(|e| e.to_string())?
726 
                .heads;
727 
            let closure = self
728 
                .closure_in_store(&new_state.heads)
729 
                .map_err(|e| e.to_string())?;
730 
            if let Some(h) = old_heads.iter().find(|h| !closure.contains(h)) {
731 
                return Err(format!(
732 
                    "not a fast-forward: current head {} would be dropped (use --force)",
733 
                    h.short(12)
734 
                ));
735 
            }
736 
        }
737 
        if let Some(p) = policy {
738 
            let Some(sa) = &u.attestation else {
739 
                return Err(format!(
740 
                    "{:?} requires a signed reference attestation under this repository's policy",
741 
                    u.name
742 
                ));
743 
            };
744 
            let signer = sa
745 
                .sigs
746 
                .first()
747 
                .map(|s| s.key)
748 
                .ok_or("attestation carries no signature")?;
749 
            if !p.authorizes(&signer, &u.name) && !self.delegate_authorized(p, &signer, &u.name) {
750 
                return Err(format!(
751 
                    "key {} may not update {:?} under this repository's policy",
752 
                    signer.short(12),
753 
                    u.name
754 
                ));
755 
            }
756 
            let old_heads = self
757 
                .store
758 
                .get_state(&current)
759 
                .map_err(|e| e.to_string())?
760 
                .heads;
761 
            self.state_allowed(&old_heads, &new_state.heads, p, &u.name)?;
762 
        }
763 
        if let Some(sa) = &u.attestation {
764 
            let last = self
765 
                .latest_ref_attest(&u.name)
766 
                .map_err(|e| e.to_string())?
767 
                .and_then(|(_, a)| match a.attest.body {
768 
                    AttestBody::Ref { serial, .. } => Some(serial),
769 
                    _ => None,
770 
                });
771 
            self.check_ref_attest(sa, &u.name, &u.old_state, &u.new_state, last, false)?;
772 
            let r = self
773 
                .store
774 
                .put_attest(&sa.attest)
775 
                .map_err(|e| e.to_string())?;
776 
            for sig in &sa.sigs {
777 
                self.store
778 
                    .put_signature(&r, sig)
779 
                    .map_err(|e| e.to_string())?;
780 
            }
781 
            self.set_ref_attest(&u.name, &r)
782 
                .map_err(|e| e.to_string())?;
783 
        }
784 
        view.bookmarks.insert(u.name.clone(), u.new_state);
785 
        Ok(())
786 
    }
787
788 
    // ------------------------------------------------------------ client side
789
790 
    fn remote_url(&self, name: &str) -> Result<String> {
791 
        self.config.remotes.get(name).cloned().ok_or_else(|| {
792 
            RepoError::Msg(format!(
793 
                "no remote named {name:?}; add one with `oxy remote add`"
794 
            ))
795 
        })
796 
    }
797
798 
    /// Credentials and trust for a remote: `remote.<name>.token` (else
799 
    /// `$OXY_TOKEN`) and `remote.<name>.ca` (else `$OXY_CA`).
800 
    /// Refuse a remote that is another repository. An **unbound** remote
801 
    /// (id all zero: a hosted repository nobody has pushed to) is accepted
802 
    /// for pushes, which bind it to this repository's id (spec §16.1).
803 
    fn check_remote_id(
804 
        &self,
805 
        remote: &dyn crate::protocol::Remote,
806 
        remote_name: &str,
807 
        allow_unbound: bool,
808 
    ) -> Result<()> {
809 
        let theirs = remote.repo_id()?;
810 
        if theirs == self.id()? {
811 
            return Ok(());
812 
        }
813 
        if theirs == crate::protocol::UNBOUND_ID {
814 
            if allow_unbound {
815 
                return Ok(());
816 
            }
817 
            return fail(format!(
818 
                "remote {remote_name:?} is empty and unbound: push to it first"
819 
            ));
820 
        }
821 
        fail(format!(
822 
            "remote {remote_name:?} is a different repository (repository IDs differ); check its URL with `oxy remote list`"
823 
        ))
824 
    }
825
826 
    pub(crate) fn remote_options(&self, name: &str) -> RemoteOptions {
827 
        RemoteOptions {
828 
            repo_id: self.id().ok(),
829 
            token: self
830 
                .config
831 
                .remote_tokens
832 
                .get(name)
833 
                .cloned()
834 
                .or_else(|| std::env::var("OXY_TOKEN").ok()),
835 
            ca: self
836 
                .config
837 
                .remote_cas
838 
                .get(name)
839 
                .map(PathBuf::from)
840 
                .or_else(|| std::env::var("OXY_CA").ok().map(PathBuf::from)),
841 
        }
842 
    }
843
844 
    /// Push seal attestations on their own (hub spec §7.4): a bundle with
845 
    /// no changes and no reference updates, which the receiver stores.
846 
    pub fn push_seals(&self, remote_name: &str, seals: &[ObjectRef]) -> Result<()> {
847 
        let remote = self.open_named_remote(remote_name)?;
848 
        self.check_remote_id(remote.as_ref(), remote_name, false)?;
849 
        let mut bundle = Bundle::default();
850 
        for r in seals {
851 
            let attest = self.store.get_attest(r)?;
852 
            let sigs = self.store.signatures(r)?;
853 
            bundle
854 
                .attests
855 
                .push(crate::protocol::SignedAttest { attest, sigs });
856 
        }
857 
        let results = remote.push(bundle, vec![], None, vec![])?;
858 
        if let Some(r) = results.iter().find(|r| !r.ok) {
859 
            return fail(format!("{}: {}", r.name, r.reason));
860 
        }
861 
        Ok(())
862 
    }
863
864 
    /// The remote whose URL starts with `base` (a hub), if configured.
865 
    pub fn remote_for_url(&self, base: &str) -> Option<String> {
866 
        let base = base.trim_end_matches('/');
867 
        self.config
868 
            .remotes
869 
            .iter()
870 
            .find(|(_, url)| url.trim_end_matches('/') == base)
871 
            .map(|(name, _)| name.clone())
872 
    }
873
874 
    /// Open a remote by name or, failing that, by URL with the default
875 
    /// credentials (`OXY_TOKEN`, `OXY_CA`).
876 
    pub fn open_remote_at(&self, url: &str) -> Result<(String, Box<dyn crate::protocol::Remote>)> {
877 
        if let Some(name) = self.remote_for_url(url) {
878 
            return Ok((name.clone(), self.open_named_remote(&name)?));
879 
        }
880 
        let options = RemoteOptions {
881 
            token: std::env::var("OXY_TOKEN").ok(),
882 
            ca: std::env::var("OXY_CA").ok().map(PathBuf::from),
883 
            repo_id: self.id().ok(),
884 
        };
885 
        Ok((url.to_string(), open_remote(url, &options)?))
886 
    }
887
888 
    /// Credentials for a URL: those of the configured remote with that
889 
    /// URL, else the environment's.
890 
    pub fn options_for_url(&self, url: &str) -> RemoteOptions {
891 
        match self.remote_for_url(url) {
892 
            Some(name) => self.remote_options(&name),
893 
            None => RemoteOptions {
894 
                token: std::env::var("OXY_TOKEN").ok(),
895 
                ca: std::env::var("OXY_CA").ok().map(PathBuf::from),
896 
                repo_id: self.id().ok(),
897 
            },
898 
        }
899 
    }
900
901 
    fn open_named_remote(&self, name: &str) -> Result<Box<dyn crate::protocol::Remote>> {
902 
        open_remote(&self.remote_url(name)?, &self.remote_options(name))
903 
    }
904
905 
    fn serial_path(&self, remote: &str, bookmark: &str) -> PathBuf {
906 
        self.oxy
907 
            .join("remotes")
908 
            .join(remote)
909 
            .join(format!("{bookmark}.serial"))
910 
    }
911
912 
    fn last_seen_serial(&self, remote: &str, bookmark: &str) -> Option<u64> {
913 
        fs::read_to_string(self.serial_path(remote, bookmark))
914 
            .ok()
915 
            .and_then(|s| s.trim().parse().ok())
916 
    }
917
918 
    fn record_serial(&self, remote: &str, bookmark: &str, serial: u64) -> Result<()> {
919 
        let p = self.serial_path(remote, bookmark);
920 
        fs::create_dir_all(p.parent().unwrap())?;
921 
        write_atomic(&p, serial.to_string().as_bytes())
922 
    }
923
924 
    fn policy_serial_path(&self, remote: &str) -> PathBuf {
925 
        self.oxy.join("remotes").join(remote).join("policy.serial")
926 
    }
927
928 
    /// The highest policy serial `remote` has ever presented.
929 
    fn remote_policy_serial(&self, remote: &str) -> Option<u64> {
930 
        fs::read_to_string(self.policy_serial_path(remote))
931 
            .ok()
932 
            .and_then(|s| s.trim().parse().ok())
933 
    }
934
935 
    fn record_policy_serial(&self, remote: &str, serial: u64) -> Result<()> {
936 
        let p = self.policy_serial_path(remote);
937 
        fs::create_dir_all(p.parent().unwrap())?;
938 
        write_atomic(&p, serial.to_string().as_bytes())
939 
    }
940
941 
    fn lazy_dir(&self) -> PathBuf {
942 
        self.oxy.join("lazy")
943 
    }
944
945 
    /// Remember that `blob` was withheld by `remote` (spec §13.5).
946 
    fn register_lazy(&self, blob: &ObjectRef, remote: &str) -> Result<()> {
947 
        fs::create_dir_all(self.lazy_dir())?;
948 
        write_atomic(&self.lazy_dir().join(blob.to_hex()), remote.as_bytes())
949 
    }
950
951 
    /// Which remote promised an absent blob, if any.
952 
    pub fn lazy_remote(&self, blob: &ObjectRef) -> Option<String> {
953 
        fs::read_to_string(self.lazy_dir().join(blob.to_hex()))
954 
            .ok()
955 
            .map(|s| s.trim().to_string())
956 
    }
957
958 
    /// Fetch an absent blob (and its chunks) from the remote that promised it.
959 
    pub(crate) fn fetch_lazy_blob(&self, blob: &ObjectRef) -> Result<()> {
960 
        let Some(remote_name) = self.lazy_remote(blob) else {
961 
            return Err(RepoError::Store(StoreError::NotFound(*blob)));
962 
        };
963 
        let remote = self.open_named_remote(&remote_name)?;
964 
        let objects = remote.objects(&[*blob])?;
965 
        for (ty, body) in objects {
966 
            if matches!(ty, ObjectType::Blob | ObjectType::Chunk) {
967 
                self.store.put(ty, &body)?;
968 
            }
969 
        }
970 
        if !self.store.has(blob) {
971 
            return fail(format!(
972 
                "{remote_name} did not send blob {}",
973 
                blob.short(12)
974 
            ));
975 
        }
976 
        let _ = fs::remove_file(self.lazy_dir().join(blob.to_hex()));
977 
        Ok(())
978 
    }
979
980 
    /// After importing from `remote`, record every blob the changes reference
981 
    /// that the store lacks as lazily available from that remote.
982 
    fn register_missing_blobs(&self, changes: &[ChangeHash], remote: &str) -> Result<usize> {
983 
        let mut n = 0;
984 
        for h in changes {
985 
            let c = self.store.get_change(h)?;
986 
            for e in &c.edits {
987 
                if let Edit::Replace { old, new, .. } = e {
988 
                    for b in [old, new].into_iter().flatten() {
989 
                        if !self.store.has(b) {
990 
                            self.register_lazy(b, remote)?;
991 
                            n += 1;
992 
                        }
993 
                    }
994 
                }
995 
            }
996 
        }
997 
        Ok(n)
998 
    }
999
1000 
    /// Every head this repository knows: bookmarks, remote tracking, working copy.
1001 
    pub fn known_heads(&self, view: &View) -> Result<Vec<ChangeHash>> {
1002 
        let mut have: BTreeSet<ChangeHash> = BTreeSet::new();
1003 
        for st in view
1004 
            .bookmarks
1005 
            .values()
1006 
            .chain(view.remotes.values().flat_map(|b| b.values()))
1007 
        {
1008 
            if let Ok(s) = self.store.get_state(st) {
1009 
                have.extend(s.heads);
1010 
            }
1011 
        }
1012 
        have.extend(view.workspaces.values().copied());
1013 
        Ok(have.into_iter().collect())
1014 
    }
1015
1016 
    /// Fetch every bookmark of a remote into `remotes/<name>/bookmarks/*` (spec §10.2).
1017 
    pub fn fetch(&self, remote_name: &str) -> Result<FetchReport> {
1018 
        let remote = self.open_named_remote(remote_name)?;
1019 
        self.check_remote_id(remote.as_ref(), remote_name, false)?;
1020 
        let resp = remote.refs()?;
1021 
        // Trust policy (spec §14.5). Adopt the remote's policy when it is newer
1022 
        // and signed by roots we trust, or on first contact. A remote that
1023 
        // once presented a policy may never present none or an older one:
1024 
        // that is a downgrade. A remote that never presented one is
1025 
        // unverified, and this fetch is checked only as far as possible.
1026 
        let local_policy = self.current_policy()?.map(|(_, sp)| sp.policy);
1027 
        let seen = self.remote_policy_serial(remote_name);
1028 
        let mut unverified = false;
1029 
        match &resp.policy {
1030 
            Some(sp) => {
1031 
                if seen.is_some_and(|s| sp.policy.serial < s) {
1032 
                    return fail(format!("{remote_name} presents policy serial {} but presented {} before: refusing the downgrade", sp.policy.serial, seen.unwrap()));
1033 
                }
1034 
                match &local_policy {
1035 
                    Some(l) if sp.policy.serial < l.serial => {}
1036 
                    Some(l) if sp.policy.serial == l.serial => {
1037 
                        if sp.policy.hash() != l.hash() {
1038 
                            return fail(format!(
1039 
                                "{remote_name} presents a different policy with the same serial {}",
1040 
                                l.serial
1041 
                            ));
1042 
                        }
1043 
                    }
1044 
                    _ => {
1045 
                        self.adopt_policy_chain(
1046 
                            &resp.history,
1047 
                            sp,
1048 
                            &format!("oxy fetch {remote_name}"),
1049 
                        )
1050 
                        .map_err(|e| RepoError::Msg(format!("policy from {remote_name}: {e}")))?;
1051 
                    }
1052 
                }
1053 
                self.record_policy_serial(remote_name, sp.policy.serial)?;
1054 
            }
1055 
            None => {
1056 
                if seen.is_some() {
1057 
                    return fail(format!("{remote_name} presented a policy before but has none now: refusing the downgrade"));
1058 
                }
1059 
                unverified = true;
1060 
            }
1061 
        }
1062 
        let policy = if unverified {
1063 
            None
1064 
        } else {
1065 
            self.current_policy()?.map(|(_, sp)| sp.policy)
1066 
        };
1067 
        let (op_ref, op) = self.head_op()?;
1068 
        let mut view = op.view.clone();
1069 
        let have = self.known_heads(&view)?;
1070 
        let mut report = Vec::new();
1071 
        let max_blob = self.config.max_blob;
1072 
        for r in resp.refs {
1073 
            let needed = remote.negotiate(&have, &r.heads)?;
1074 
            let bundle = remote.fetch(&needed, max_blob)?;
1075 
            // Changes are not individually re-verified here: the bookmark's
1076 
            // attestation (checked below) binds its whole state, and the
1077 
            // receiver of the push verified the added changes at that time.
1078 
            let imported = self.import_bundle(&bundle, false)?;
1079 
            if max_blob.is_some() {
1080 
                self.register_missing_blobs(&imported, remote_name)?;
1081 
            }
1082 
            for h in &r.heads {
1083 
                if !self.store.has(h) {
1084 
                    return fail(format!("remote did not send head {}", h.short(12)));
1085 
                }
1086 
            }
1087 
            let state = self.store.put_state(&StateObject::new(r.heads.clone()))?;
1088 
            if state != r.state {
1089 
                return fail(format!(
1090 
                    "remote state {} does not match its heads",
1091 
                    r.state.short(12)
1092 
                ));
1093 
            }
1094 
            if let Some(p) = &policy {
1095 
                let Some(sa) = &r.attestation else {
1096 
                    return fail(format!(
1097 
                        "{remote_name}/{} has no attestation, which its policy requires",
1098 
                        r.name
1099 
                    ));
1100 
                };
1101 
                let signer = sa
1102 
                    .sigs
1103 
                    .first()
1104 
                    .map(|s| s.key)
1105 
                    .ok_or_else(|| RepoError::Msg("attestation carries no signature".into()))?;
1106 
                if !p.authorizes(&signer, &r.name) && !self.delegate_authorized(p, &signer, &r.name) {
1107 
                    return fail(format!(
1108 
                        "{remote_name}/{}: attested by {}, which the policy does not authorize for this bookmark; a policy owner can grant it with `oxy policy grant`",
1109 
                        r.name,
1110 
                        signer.short(12)
1111 
                    ));
1112 
                }
1113 
            }
1114 
            if let Some(sa) = &r.attestation {
1115 
                let AttestBody::Ref {
1116 
                    old_state,
1117 
                    new_state,
1118 
                    ..
1119 
                } = &sa.attest.body
1120 
                else {
1121 
                    return fail("remote sent a non-ref attestation for a bookmark");
1122 
                };
1123 
                let (old_state, new_state) = (*old_state, *new_state);
1124 
                let serial = self
1125 
                    .check_ref_attest(
1126 
                        sa,
1127 
                        &r.name,
1128 
                        &old_state,
1129 
                        &new_state,
1130 
                        self.last_seen_serial(remote_name, &r.name),
1131 
                        true,
1132 
                    )
1133 
                    .map_err(|e| {
1134 
                        RepoError::Msg(format!("attestation for {}/{}: {e}", remote_name, r.name))
1135 
                    })?;
1136 
                if new_state != r.state {
1137 
                    return fail(format!(
1138 
                        "attestation for {}/{} does not cover its current state",
1139 
                        remote_name, r.name
1140 
                    ));
1141 
                }
1142 
                let ar = self.store.put_attest(&sa.attest)?;
1143 
                for sig in &sa.sigs {
1144 
                    self.store.put_signature(&ar, sig)?;
1145 
                }
1146 
                self.record_serial(remote_name, &r.name, serial)?;
1147 
            }
1148 
            view.remotes
1149 
                .entry(remote_name.to_string())
1150 
                .or_default()
1151 
                .insert(r.name.clone(), state);
1152 
            report.push((r.name, r.heads, imported.len()));
1153 
        }
1154 
        let mut new_tags = 0;
1155 
        for t in &resp.tags {
1156 
            if view.tags.contains_key(&t.name) {
1157 
                continue;
1158 
            }
1159 
            // The tag's changes must be here: fetch them if the bookmarks did not bring them.
1160 
            let missing: Vec<ChangeHash> = t
1161 
                .heads
1162 
                .iter()
1163 
                .filter(|h| !self.store.has(h))
1164 
                .copied()
1165 
                .collect();
1166 
            if !missing.is_empty() {
1167 
                let needed = remote.negotiate(&self.known_heads(&view)?, &missing)?;
1168 
                let bundle = remote.fetch(&needed, max_blob)?;
1169 
                self.import_bundle(&bundle, false)?;
1170 
            }
1171 
            self.store.put_state(&StateObject::new(t.heads.clone()))?;
1172 
            self.adopt_tag(&mut view, t, policy.as_ref())
1173 
                .map_err(|e| RepoError::Msg(format!("{remote_name} {}: {e}", t.name)))?;
1174 
            new_tags += 1;
1175 
        }
1176 
        if view != op.view {
1177 
            self.record_op(&[op_ref], &format!("oxy fetch {remote_name}"), view)?;
1178 
        }
1179 
        let _ = self.run_hook(
1180 
            "post-fetch",
1181 
            &format!(
1182 
                "{{\"event\":\"post-fetch\",\"remote\":{},\"bookmarks\":{}}}",
1183 
                json_str(remote_name),
1184 
                json_array(report.iter().map(|(n, heads, _)| format!(
1185 
                    "{{\"name\":{},\"heads\":{}}}",
1186 
                    json_str(n),
1187 
                    json_array(heads.iter().map(|h| json_str(&h.to_hex())))
1188 
                )))
1189 
            ),
1190 
        );
1191 
        Ok(FetchReport {
1192 
            refs: report,
1193 
            unverified,
1194 
            new_tags,
1195 
        })
1196 
    }
1197
1198 
    /// Shallow fetch of the remote's bookmark: its checkpoint as our base,
1199 
    /// the changes within `depth` steps of its heads, and the boundary below.
1200 
    pub fn fetch_shallow(&self, remote_name: &str, depth: u32) -> Result<usize> {
1201 
        let remote = self.open_named_remote(remote_name)?;
1202 
        self.check_remote_id(remote.as_ref(), remote_name, false)?;
1203 
        let resp = remote.refs()?;
1204 
        let bookmark = self.config.bookmark.clone();
1205 
        if let Some(sp) = &resp.policy {
1206 
            self.adopt_policy_chain(&resp.history, sp, "oxy clone --depth")
1207 
                .map_err(|e| RepoError::Msg(format!("policy from {remote_name}: {e}")))?;
1208 
            self.record_policy_serial(remote_name, sp.policy.serial)?;
1209 
        }
1210 
        let Some(r) = resp.refs.into_iter().find(|r| r.name == bookmark) else {
1211 
            return fail(format!("{remote_name} has no bookmark {bookmark:?}"));
1212 
        };
1213 
        if r.heads.is_empty() {
1214 
            return Ok(0);
1215 
        }
1216 
        // Base: the remote's checkpoint of exactly these heads.
1217 
        let cp_bundle = remote.checkpoint(&r.heads)?;
1218 
        let mut cp_ref = None;
1219 
        for (ty, body) in &cp_bundle.objects {
1220 
            let put = self.store.put(*ty, body)?;
1221 
            if *ty == ObjectType::Checkpoint {
1222 
                cp_ref = Some(put);
1223 
            }
1224 
        }
1225 
        let Some(cp_ref) = cp_ref else {
1226 
            return fail(format!("{remote_name} sent no checkpoint"));
1227 
        };
1228 
        self.install_checkpoint(&bookmark, &cp_ref)?;
1229 
        // History window.
1230 
        let wanted = remote.shallow(&r.heads, depth)?;
1231 
        let bundle = remote.fetch(&wanted, self.config.max_blob)?;
1232 
        let imported = self.import_bundle_shallow(&bundle, false)?;
1233 
        if self.config.max_blob.is_some() {
1234 
            self.register_missing_blobs(&imported, remote_name)?;
1235 
        }
1236 
        self.refresh_boundary(&imported)?;
1237 
        if let Some(sa) = &r.attestation {
1238 
            let ar = self.store.put_attest(&sa.attest)?;
1239 
            for sig in &sa.sigs {
1240 
                self.store.put_signature(&ar, sig)?;
1241 
            }
1242 
            if let AttestBody::Ref { serial, .. } = sa.attest.body {
1243 
                self.record_serial(remote_name, &r.name, serial)?;
1244 
            }
1245 
        }
1246 
        let state = self.store.put_state(&StateObject::new(r.heads.clone()))?;
1247 
        let (op_ref, op) = self.head_op()?;
1248 
        let mut view = op.view.clone();
1249 
        view.remotes
1250 
            .entry(remote_name.to_string())
1251 
            .or_default()
1252 
            .insert(r.name.clone(), state);
1253 
        self.record_op(
1254 
            &[op_ref],
1255 
            &format!("oxy fetch {remote_name} --depth {depth}"),
1256 
            view,
1257 
        )?;
1258 
        Ok(imported.len())
1259 
    }
1260
1261 
    /// Fetch, then take the union of the local bookmark's state with the
1262 
    /// remote's: no merge change, conflicts become reified (spec §9.4).
1263 
    pub fn pull(&self, remote_name: &str) -> Result<PullReport> {
1264 
        let _wc = self.lock_working_copy()?;
1265 
        self.fetch(remote_name)?;
1266 
        let (op_ref, op) = self.head_op()?;
1267 
        let bookmark = self.config.bookmark.clone();
1268 
        let local = self.heads_of(&op.view, &bookmark)?;
1269 
        let Some(remote_state) = op
1270 
            .view
1271 
            .remotes
1272 
            .get(remote_name)
1273 
            .and_then(|b| b.get(&bookmark))
1274 
            .copied()
1275 
        else {
1276 
            return Ok(PullReport {
1277 
                heads: local,
1278 
                changed: false,
1279 
                checked_out: false,
1280 
            });
1281 
        };
1282 
        let remote_heads = self.store.get_state(&remote_state)?.heads;
1283 
        let mut all = local.clone();
1284 
        all.extend(remote_heads);
1285 
        let st = self.load_state(&all)?;
1286 
        let mut heads = st.maximal(&all);
1287 
        heads.sort();
1288 
        let mut sorted_local = local.clone();
1289 
        sorted_local.sort();
1290 
        if heads == sorted_local {
1291 
            return Ok(PullReport {
1292 
                heads,
1293 
                changed: false,
1294 
                checked_out: false,
1295 
            });
1296 
        }
1297 
        let mut view = op.view.clone();
1298 
        view.bookmarks.insert(
1299 
            bookmark.clone(),
1300 
            self.store.put_state(&StateObject::new(heads.clone()))?,
1301 
        );
1302 
        self.record_op(&[op_ref], &format!("oxy pull {remote_name}"), view)?;
1303 
        // Follow along if the working copy was clean and on the old heads.
1304 
        let snap = self.snapshot("oxy pull")?;
1305 
        let clean = snap.wc.tree_ops.is_empty() && snap.wc.edits.is_empty();
1306 
        let mut base = snap.base.maximal(&snap.wc.deps);
1307 
        base.sort();
1308 
        let mut checked_out = false;
1309 
        if clean && base == sorted_local {
1310 
            self.checkout(&heads, false, "oxy pull (checkout)")?;
1311 
            checked_out = true;
1312 
        }
1313 
        Ok(PullReport {
1314 
            heads,
1315 
            changed: true,
1316 
            checked_out,
1317 
        })
1318 
    }
1319
1320 
    /// Push the current bookmark (spec §16.3), sealing this author's unsigned
1321 
    /// changes and attesting the reference when a key is available.
1322 
    /// Delete `bookmark` on a remote (spec §16.4): an update to the zero
1323 
    /// state, attested when we have an identity. The local bookmark, if
1324 
    /// any, is kept; only the remote-tracking entry goes.
1325 
    pub fn push_delete(&self, remote_name: &str, bookmark: &str) -> Result<Vec<RefResult>> {
1326 
        let remote = self.open_named_remote(remote_name)?;
1327 
        self.check_remote_id(remote.as_ref(), remote_name, true)?;
1328 
        let resp = remote.refs()?;
1329 
        let Some(r) = resp.refs.iter().find(|r| r.name == bookmark) else {
1330 
            return fail(format!("{remote_name} has no bookmark {bookmark}"));
1331 
        };
1332 
        if resp.policy.is_some() && self.secret_key()?.is_none() {
1333 
            return fail(format!("{remote_name} enforces a trust policy; deleting needs an identity (`oxy identity create`)"));
1334 
        }
1335 
        let attestation = match self.secret_key()? {
1336 
            Some(_) => Some(self.sign_attest(&Attest {
1337 
                repo: self.id()?,
1338 
                hlc: Hlc::now(),
1339 
                body: AttestBody::Ref {
1340 
                    name: bookmark.to_string(),
1341 
                    old_state: r.state,
1342 
                    new_state: ObjectRef::ZERO,
1343 
                    serial: r.last_serial.unwrap_or(0) + 1,
1344 
                },
1345 
            })?),
1346 
            None => None,
1347 
        };
1348 
        let results = remote.push(
1349 
            Bundle::default(),
1350 
            vec![RefUpdate {
1351 
                name: bookmark.to_string(),
1352 
                old_state: r.state,
1353 
                new_state: ObjectRef::ZERO,
1354 
                force: true,
1355 
                attestation,
1356 
            }],
1357 
            None,
1358 
            vec![],
1359 
        )?;
1360 
        if results.iter().any(|x| x.ok && x.name == bookmark) {
1361 
            let (op_ref, op) = self.head_op()?;
1362 
            let mut view = op.view.clone();
1363 
            if let Some(m) = view.remotes.get_mut(remote_name) {
1364 
                m.remove(bookmark);
1365 
            }
1366 
            self.record_op(
1367 
                &[op_ref],
1368 
                &format!("oxy push {remote_name} --delete {bookmark}"),
1369 
                view,
1370 
            )?;
1371 
        }
1372 
        Ok(results)
1373 
    }
1374
1375 
    pub fn push(&self, remote_name: &str, force: bool) -> Result<Vec<RefResult>> {
1376 
        let bookmark = self.config.bookmark.clone();
1377 
        self.push_bookmark(remote_name, &bookmark, force)
1378 
    }
1379
1380 
    /// `push` for a named bookmark (`oxy push -b NAME`).
1381 
    pub fn push_bookmark(
1382 
        &self,
1383 
        remote_name: &str,
1384 
        bookmark: &str,
1385 
        force: bool,
1386 
    ) -> Result<Vec<RefResult>> {
1387 
        let (op_ref, op) = self.head_op()?;
1388 
        if !op.view.bookmarks.contains_key(bookmark) {
1389 
            return fail(format!("no bookmark {bookmark}"));
1390 
        }
1391 
        let bookmark = bookmark.to_string();
1392 
        let local_heads = self.heads_of(&op.view, &bookmark)?;
1393 
        // pre-push hook: may veto before the remote is contacted.
1394 
        self.run_hook(
1395 
            "pre-push",
1396 
            &format!(
1397 
                "{{\"event\":\"pre-push\",\"remote\":{},\"bookmark\":{},\"heads\":{}}}",
1398 
                json_str(remote_name),
1399 
                json_str(&bookmark),
1400 
                json_array(local_heads.iter().map(|h| json_str(&h.to_hex())))
1401 
            ),
1402 
        )?;
1403 
        let remote = self.open_named_remote(remote_name)?;
1404 
        self.check_remote_id(remote.as_ref(), remote_name, true)?;
1405 
        let resp = remote.refs()?;
1406 
        let local_policy = self.current_policy()?.map(|(_, sp)| sp);
1407 
        let resp_policy_serial = resp.policy.as_ref().map(|p| p.policy.serial);
1408 
        let policy_to_send = match (&local_policy, &resp.policy) {
1409 
            (Some(l), Some(r)) if l.policy.serial > r.policy.serial => Some(l.clone()),
1410 
            (Some(l), None) => Some(l.clone()),
1411 
            (Some(l), Some(r)) if l.policy.serial < r.policy.serial => {
1412 
                return fail(format!(
1413 
                    "{remote_name} has a newer policy (serial {}); fetch first",
1414 
                    r.policy.serial
1415 
                ));
1416 
            }
1417 
            _ => None,
1418 
        };
1419 
        let remote_has_policy = resp.policy.is_some() || policy_to_send.is_some();
1420 
        if remote_has_policy && self.secret_key()?.is_none() {
1421 
            return fail(format!("{remote_name} enforces a trust policy; pushing needs an identity (`oxy identity create`)"));
1422 
        }
1423 
        let remote_tags: BTreeSet<String> = resp.tags.iter().map(|t| t.name.clone()).collect();
1424 
        let tags_to_send: Vec<crate::protocol::TagRef> = self
1425 
            .tag_refs()?
1426 
            .into_iter()
1427 
            .filter(|t| !remote_tags.contains(&t.name))
1428 
            .collect();
1429 
        let refs = resp.refs;
1430 
        let empty = self.store.put_state(&StateObject::new(vec![]))?;
1431 
        let (remote_state, remote_heads, last_serial) =
1432 
            match refs.iter().find(|r| r.name == bookmark) {
1433 
                Some(r) => (r.state, r.heads.clone(), r.last_serial),
1434 
                None => (empty, vec![], None),
1435 
            };
1436 
        let new_state = self
1437 
            .store
1438 
            .put_state(&StateObject::new(local_heads.clone()))?;
1439 
        // A push that carries a policy re-attests the bookmark even when its
1440 
        // state is unchanged, so the current attestation is always by a key
1441 
        // the current policy authorizes (a revoked key's attestation would
1442 
        // otherwise be refused by every later fetch).
1443 
        if new_state == remote_state && policy_to_send.is_none() && tags_to_send.is_empty() {
1444 
            return Ok(vec![RefResult {
1445 
                name: bookmark,
1446 
                ok: true,
1447 
                reason: "already up to date".into(),
1448 
            }]);
1449 
        }
1450 
        for h in &remote_heads {
1451 
            if !self.store.has(h) {
1452 
                return fail(format!(
1453 
                    "the remote has change {} which you do not; pull first (`oxy pull {remote_name}`), then push again",
1454 
                    h.short(12)
1455 
                ));
1456 
            }
1457 
        }
1458 
        if !force {
1459 
            let closure = self.closure_in_store(&local_heads)?;
1460 
            if let Some(h) = remote_heads.iter().find(|h| !closure.contains(h)) {
1461 
                return fail(format!("not a fast-forward: remote head {} is not in your state; pull first or use --force", h.short(12)));
1462 
            }
1463 
        }
1464 
        let to_send = self.negotiate(&remote_heads, &local_heads)?;
1465 
        let mut bundle = self.bundle_for(&to_send)?;
1466 
        let key = self.secret_key()?.map(|(k, _)| k);
1467 
        if let Some(key) = key {
1468 
            // Seal this author's changes that carry no valid authenticator,
1469 
            // and adopt anonymous ones (zero author, spec §14.4).
1470 
            let mut unsigned = Vec::new();
1471 
            for h in &to_send {
1472 
                let c = self.store.get_change(h)?;
1473 
                if (c.author == key || c.author.is_zero())
1474 
                    && !matches!(self.authenticate_change(h)?, SignatureStatus::Valid { .. })
1475 
                {
1476 
                    unsigned.push(*h);
1477 
                }
1478 
            }
1479 
            for chunk in unsigned.chunks(crate::attest::MAX_SEAL_HASHES) {
1480 
                let sa = self.sign_attest(&Attest::seal(self.id()?, chunk.to_vec()))?;
1481 
                bundle.attests.push(sa);
1482 
            }
1483 
            bundle = self.bundle_for(&to_send)?;
1484 
        }
1485 
        bundle.objects.push((
1486 
            ObjectType::State,
1487 
            StateObject::new(local_heads.clone()).encode(),
1488 
        ));
1489 
        let attestation = match key {
1490 
            Some(_) => Some(self.sign_attest(&Attest {
1491 
                repo: self.id()?,
1492 
                hlc: Hlc::now(),
1493 
                body: AttestBody::Ref {
1494 
                    name: bookmark.clone(),
1495 
                    old_state: remote_state,
1496 
                    new_state,
1497 
                    serial: next_serial(last_serial),
1498 
                },
1499 
            })?),
1500 
            None => None,
1501 
        };
1502 
        let serial = attestation.as_ref().and_then(|a| match a.attest.body {
1503 
            AttestBody::Ref { serial, .. } => Some(serial),
1504 
            _ => None,
1505 
        });
1506 
        let sent_serial = policy_to_send.as_ref().map(|p| p.policy.serial);
1507 
        // Tag states must be present on the remote: bundle their changes too.
1508 
        for t in &tags_to_send {
1509 
            let extra = self.negotiate(&remote_heads, &t.heads)?;
1510 
            let extra: Vec<ChangeHash> =
1511 
                extra.into_iter().filter(|h| !to_send.contains(h)).collect();
1512 
            if !extra.is_empty() {
1513 
                let more = self.bundle_for(&extra)?;
1514 
                bundle.changes.extend(more.changes);
1515 
                bundle.attests.extend(more.attests);
1516 
                bundle.objects.extend(more.objects);
1517 
            }
1518 
            bundle.objects.push((
1519 
                ObjectType::State,
1520 
                StateObject::new(t.heads.clone()).encode(),
1521 
            ));
1522 
        }
1523 
        if let Some(l) = &policy_to_send {
1524 
            let remote_serial = resp_policy_serial;
1525 
            bundle.policies = self
1526 
                .policy_history()?
1527 
                .into_iter()
1528 
                .filter(|sp| {
1529 
                    remote_serial.is_none_or(|r| sp.policy.serial > r)
1530 
                        && sp.policy.serial < l.policy.serial
1531 
                })
1532 
                .collect();
1533 
        }
1534 
        let results = remote.push(
1535 
            bundle,
1536 
            vec![RefUpdate {
1537 
                name: bookmark.clone(),
1538 
                old_state: remote_state,
1539 
                new_state,
1540 
                force,
1541 
                attestation,
1542 
            }],
1543 
            policy_to_send,
1544 
            tags_to_send,
1545 
        )?;
1546 
        if let (Some(serial), true) = (
1547 
            sent_serial,
1548 
            results.iter().any(|r| r.ok && r.name == "policy"),
1549 
        ) {
1550 
            self.record_policy_serial(remote_name, serial)?;
1551 
        }
1552 
        if results.iter().any(|r| r.ok && r.name == bookmark) {
1553 
            let mut view = op.view.clone();
1554 
            view.remotes
1555 
                .entry(remote_name.to_string())
1556 
                .or_default()
1557 
                .insert(bookmark.clone(), new_state);
1558 
            self.record_op(&[op_ref], &format!("oxy push {remote_name}"), view)?;
1559 
            if let Some(s) = serial {
1560 
                self.record_serial(remote_name, &bookmark, s)?;
1561 
            }
1562 
        }
1563 
        Ok(results)
1564 
    }
1565
1566 
    /// Clone a remote into `dest`: same repository ID, `origin` remote,
1567 
    /// bookmark set to the remote's, working copy checked out.
1568 
    pub fn clone(url: &str, dest: &Path) -> Result<Repo> {
1569 
        Self::clone_with(url, dest, None, &[])
1570 
    }
1571
1572 
    /// Clone, leaving blobs above `max_blob` bytes to be fetched on first
1573 
    /// read, and materializing only `sparse` paths (which implies lazy blobs
1574 
    /// unless a size is given, so out-of-scope binaries are never fetched).
1575 
    pub fn clone_with(
1576 
        url: &str,
1577 
        dest: &Path,
1578 
        max_blob: Option<u64>,
1579 
        sparse: &[String],
1580 
    ) -> Result<Repo> {
1581 
        Self::clone_full(url, dest, max_blob, sparse, None)
1582 
    }
1583
1584 
    /// Shallow clone (spec §17): a checkpoint of the bookmark's heads plus the
1585 
    /// changes within `depth` steps of them; the rest is the boundary.
1586 
    pub fn clone_shallow(
1587 
        url: &str,
1588 
        dest: &Path,
1589 
        depth: u32,
1590 
        max_blob: Option<u64>,
1591 
        sparse: &[String],
1592 
    ) -> Result<Repo> {
1593 
        Self::clone_full(url, dest, max_blob, sparse, Some(depth))
1594 
    }
1595
1596 
    fn clone_full(
1597 
        url: &str,
1598 
        dest: &Path,
1599 
        max_blob: Option<u64>,
1600 
        sparse: &[String],
1601 
        depth: Option<u32>,
1602 
    ) -> Result<Repo> {
1603 
        let options = RemoteOptions {
1604 
            token: std::env::var("OXY_TOKEN").ok(),
1605 
            ca: std::env::var("OXY_CA").ok().map(PathBuf::from),
1606 
            repo_id: None,
1607 
        };
1608 
        let remote = open_remote(url, &options)?;
1609 
        let id = remote.repo_id()?;
1610 
        if id == crate::protocol::UNBOUND_ID {
1611 
            return fail(format!(
1612 
                "{url} is empty and unbound: push a repository to it first"
1613 
            ));
1614 
        }
1615 
        let mut repo = Repo::init_with_id(dest, id)?;
1616 
        repo.config.set("remote.origin.url", url)?;
1617 
        if let Some(m) = max_blob {
1618 
            repo.config.set("filter.max-blob", &m.to_string())?;
1619 
        } else if !sparse.is_empty() {
1620 
            repo.config.set("filter.max-blob", "0")?;
1621 
        }
1622 
        if !sparse.is_empty() {
1623 
            repo.config.set("filter.paths", &sparse.join(","))?;
1624 
        }
1625 
        repo.save_config()?;
1626 
        if let Some(depth) = depth {
1627 
            repo.fetch_shallow("origin", depth)?;
1628 
        } else {
1629 
            repo.fetch("origin")?;
1630 
        }
1631 
        let (op_ref, op) = repo.head_op()?;
1632 
        let bookmark = repo.config.bookmark.clone();
1633 
        if let Some(state) = op
1634 
            .view
1635 
            .remotes
1636 
            .get("origin")
1637 
            .and_then(|b| b.get(&bookmark))
1638 
            .copied()
1639 
        {
1640 
            let heads = repo.store.get_state(&state)?.heads;
1641 
            let mut view = op.view.clone();
1642 
            view.bookmarks.insert(bookmark, state);
1643 
            repo.record_op(&[op_ref], &format!("oxy clone {url}"), view)?;
1644 
            repo.checkout(&heads, false, "oxy clone (checkout)")?;
1645 
        }
1646 
        Ok(repo)
1647 
    }
1648 
}
1649
1650 
/// The serial of a reference's next attestation: one more than the last the
1651 
/// remote reports, or, for a bookmark the remote does not have, the clock in
1652 
/// milliseconds, so a bookmark created again after a deletion goes past the
1653 
/// deletion's serial the remote keeps.
1654 
fn next_serial(last: Option<u64>) -> u64 {
1655 
    match last {
1656 
        Some(l) => l + 1,
1657 
        None => Hlc::now().wall_ms.max(1),
1658 
    }
1659 
}