Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 5 additions & 5 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -106,7 +106,7 @@ the project tree if desired.

## Capability map (what's built, by phase)

All 36 phases, P37a, P37b-i, P37b-ii and P37c are built and tested. One line of current fact per phase; the
All 36 phases, P37a, P37b-i, P37b-ii, P37c and P37d are built and tested. One line of current fact per phase; the
authoritative rationale and full semantics live in the linked ADR, the design
in `ARCHITECTURE.md`. The old per-phase narrative log this table replaced is
archived verbatim at `docs/archive/claude-md-phase-log-2026-07.md` — do not
Expand Down Expand Up @@ -153,7 +153,8 @@ the code, those win.
| P36 | Bucket WAL remotes (sc+wal://, sc+s3://): immutable packs + CAS'd manifest, checkpoints + log-tail cold start, bucket-backed `sc serve --store` with disposable instances | [0046](docs/adr/0046-wal-bucket-remotes.md) |
| P37a | Want-by-id fetch: batched `GetObjects` verb (wire v5), opt-in `.sc/promisor-lazy`, `sc cat <ref>:<path>` fills only the absent trees and blob on its path; `Store::get` stays network-free; sealed objects refused by kind; sparse widen and the lifted P27 refusals are P37b | [0047](docs/adr/0047-want-by-id-fetch-and-gap-fill.md) |
| P37b-i | Presence-based partial clones: push, verify and gc walk what the store holds (`reachable_objects_partial`), not the fetch filter; push checks every gap id against the destination before sending; a view gap fails with `GapInView` before any write (preflight at the top of `materialize`, plus `undo` and `sparse set`); a partial clone fetches from its origin only. 37b-ii: on a lazy, online clone `ensure_view` fills the view closure by id before switch, fast-forward, undo and `sparse set`, `sparse set` may widen past the filter, a by-id reply is capped at `min(--max-pack-size, 512 MiB)` and a refused batch is split. | [0048](docs/adr/0048-presence-based-partial-clones.md) |
| P37c | Merge, cherry-pick and rebase on a partial clone: a tree-recursive engine (`merge_trees`) carries a subtree by id when the sides agree and no protection rule applies, reads only where they differ or a rule intersects, and on a lazy, online clone fills what it asks for by id outside the store lock (a non-lazy clone gets the gap error with `sc backfill <path>`); a carried protected subtree keeps the complete input wrap union; a conflict inside the view is marked and resolved like on a full clone (`sc conflicts`/`sc resolve`/`merge --abort`/`sc commit`; the out-of-view part is grafted from the decided root), while a conflict outside the view, or a result that must be sealed outside it, is refused before any ref, merge-state or working-tree change (fetched objects stay). A subtree identical on all three sides is carried even under a protection rule. Cherry-pick and rebase use the same engine (`replay_commit`): the fold's accumulator may hold absent subtrees, the view is filled before the final write, and a stopped pick or rebase keeps its carried subtrees in the decided root. Mode-only edits now merge and a file/directory collision fails before any write, on full clones too. Sessions are undecided | [0049](docs/adr/0049-merge-on-partial-clones.md) |
| P37c | Merge, cherry-pick and rebase on a partial clone: a tree-recursive engine (`merge_trees`) carries a subtree by id when the sides agree and no protection rule applies, reads only where they differ or a rule intersects, and on a lazy, online clone fills what it asks for by id outside the store lock (a non-lazy clone gets the gap error with `sc backfill <path>`); a carried protected subtree keeps the complete input wrap union; a conflict inside the view is marked and resolved like on a full clone (`sc conflicts`/`sc resolve`/`merge --abort`/`sc commit`; the out-of-view part is grafted from the decided root), while a conflict outside the view, or a result that must be sealed outside it, is refused before any ref, merge-state or working-tree change (fetched objects stay). A subtree identical on all three sides is carried even under a protection rule. Cherry-pick and rebase use the same engine (`replay_commit`): the fold's accumulator may hold absent subtrees, the view is filled before the final write, and a stopped pick or rebase keeps its carried subtrees in the decided root. Mode-only edits now merge and a file/directory collision fails before any write, on full clones too. | [0049](docs/adr/0049-merge-on-partial-clones.md) |
| P37d | Agent sessions on a partial clone: `sc ws fork`/`run`/`harvest`/`abandon` and `sc work` work; a workspace or agent sees the host's sparse view only (`sc work` no longer gets a complete tree there), the view closure is filled (lazy, online) or refused with the gap error before anything is written, a workspace commit grafts the out-of-view subtrees from the base without reading them, and harvest lands through the ADR-0049 merge (any conflict falls back to a `work-<i>` branch as on a full clone) | [0050](docs/adr/0050-sessions-on-partial-clones.md) |

## Standing boundaries & gotchas

Expand All @@ -169,10 +170,9 @@ transport-adjacent. The rest, imperatively:
renderer has five typed repository commands, no general filesystem/shell
capability, and no DTO field capable of carrying protected ciphertext or
identity material.
- **Partial clones refuse `sc ws fork`/`harvest`,
`sc work`, `sc export`, `sparse disable`, an empty `sparse set` (and, on a non-lazy clone, one outside the filter), `sc rewrap`,
- **Partial clones refuse `sc export`, `sparse disable`, an empty `sparse set` (and, on a non-lazy clone, one outside the filter), `sc rewrap`,
`sc grant`/`revoke`, creating, switching to or leaving a private branch, a merge, cherry-pick or rebase whose conflict lies outside the view or needs sealing outside it (no ref, state or working-tree change), `sc push` to a git remote, and
`sc fetch` from any native remote but the promisor origin.** `sc merge`, `sc cherry-pick` and `sc rebase` work, including conflicts inside the view (P37c). `sc backfill --all`
`sc fetch` from any native remote but the promisor origin.** `sc merge`, `sc cherry-pick` and `sc rebase` work, including conflicts inside the view (P37c). `sc ws` and `sc work` work too (ADR-0050): workspaces and agents see the clone's view only, and harvest lands through the same merge. `sc backfill --all`
converts to a genuine full clone and re-enables them. The filter records what
a clone *asked for*, not what is present: after a fetch an in-filter object
can be absent. On a lazy, online clone a switch, fast-forward, rebase, undo
Expand Down
8 changes: 4 additions & 4 deletions ROADMAP.md
Original file line number Diff line number Diff line change
Expand Up @@ -558,12 +558,12 @@ clone: the view closure is filled by id before switch, fast-forward, undo and
`sparse disable` stay refused. Design and open questions in
[ADR-0048](docs/adr/0048-presence-based-partial-clones.md).

**P37c — merge on partial clones (proposed; 37c-i engine, 37c-ii clean merge, 37c-iii conflicts and 37c-iv replay built).** A tree-recursive three-way merge
**P37c — merge on partial clones (built; 37c-i engine, 37c-ii clean merge, 37c-iii conflicts and 37c-iv replay).** A tree-recursive three-way merge
that carries a subtree by id where the three sides agree, checks protection
rules before carrying, never drops wraps for subtrees it does not enumerate,
and fills (lazy) or refuses (otherwise) the region where the sides differ,
the region that intersects a protection rule, and the sparse view's closure. Merges are built (`sc merge` on a partial clone): a conflict inside the view is marked, resolved with `sc conflicts`/`sc resolve`, aborted or committed like on a full clone; a conflict outside the view, or one that needs sealing outside it, is refused before any write. Cherry-pick and rebase use the same engine and conflict contract (`sc cherry-pick`, `sc rebase` and their `--continue`/`--abort` work on a partial clone); sessions
are undecided. Design in
the region that intersects a protection rule, and the sparse view's closure. Merges are built (`sc merge` on a partial clone): a conflict inside the view is marked, resolved with `sc conflicts`/`sc resolve`, aborted or committed like on a full clone; a conflict outside the view, or one that needs sealing outside it, is refused before any write. Cherry-pick and rebase use the same engine and conflict contract (`sc cherry-pick`, `sc rebase` and their `--continue`/`--abort` work on a partial clone); sessions are built (P37d, [ADR-0050](docs/adr/0050-sessions-on-partial-clones.md)): workspaces and
agents see the clone's view, and harvest lands through this merge. Design in
[ADR-0049](docs/adr/0049-merge-on-partial-clones.md).

## Completed phases (usability-first ordering)
Expand Down Expand Up @@ -774,7 +774,7 @@ scale-&-reach horizon):
workaround proves too coarse in practice.
**Now scoped as P37b (ADR-0048) and P37c (ADR-0049, Proposed):** push,
verify and gc are presence-based (built); merge is designed in ADR-0049,
with replay following it and sessions undecided.
with replay and sessions (ADR-0050) following it.
- **Blob-size/object-count clone filters (P27).** `sc clone --filter` is
prefix-only, matching the sparse path-boundary machinery already built;
git's `--filter=blob:limit` size-based filtering is a separate axis,
Expand Down
2 changes: 2 additions & 0 deletions crates/repo/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,8 @@ mod partial_merge;
#[cfg(test)]
mod partial_replay;
#[cfg(test)]
mod partial_sessions;
#[cfg(test)]
mod partial_walks;
pub mod pick_state;
pub mod private;
Expand Down
255 changes: 255 additions & 0 deletions crates/repo/src/partial_sessions.rs
Original file line number Diff line number Diff line change
@@ -0,0 +1,255 @@
//! Tests for agent sessions on a partial clone (ADR-0050): `sc ws` and
//! `sc work` workspaces see the host's view, and harvest lands through the
//! same tree-recursive merge as `sc merge` (ADR-0049).
//!
//! They reuse the merge fixture: an origin with `src/`, `docs/`, `docs/api/`
//! and `lib/`, and a `--filter src/` clone.

use crate::partial_merge::{dir_id, has, Fx, SRC_A};
use crate::refs;
use crate::workspace::WorkOptions;
use crate::ws::WsHarvestOutcome;

const SRC_FIRST: &[u8] = b"ONE\ntwo\nthree\n";
const SRC_LAST: &[u8] = b"one\ntwo\nTHREE\n";

/// `sc ws fork` lays out the view and nothing else.
#[test]
fn fork_materializes_only_the_view() {
let fx = Fx::origin("ws-view", |_| {});
let clone = fx.clone(false);
let session = clone.ws_fork(2, "t", None).unwrap();
assert_eq!(session.workspaces.len(), 2);
for ws in &session.workspaces {
assert_eq!(std::fs::read(ws.dir.join("src/a.txt")).unwrap(), SRC_A);
assert!(!ws.dir.join("docs").exists(), "docs is outside the view");
assert!(!ws.dir.join("lib").exists());
}
clone.ws_abandon(None).unwrap();
assert!(clone.ws_session().unwrap().is_none());
drop(clone);
fx.cleanup();
}

/// A workspace edit and a host edit to different lines of the same file merge
/// cleanly, and the out-of-view subtrees are carried by id, never read.
#[test]
fn harvest_lands_a_clean_merge_and_carries_the_out_of_view_subtrees() {
let fx = Fx::origin("ws-land", |_| {});
let clone = fx.clone(false);
let base = refs::read_branch_tip(clone.layout(), "main")
.unwrap()
.unwrap();
let docs = dir_id(&clone, &base, "docs");
let session = clone.ws_fork(1, "t", None).unwrap();
std::fs::write(session.workspaces[0].dir.join("src/a.txt"), SRC_FIRST).unwrap();

// The host moves on in the same file, on another line.
std::fs::write(fx.clone_root.join("src/a.txt"), SRC_LAST).unwrap();
let host_tip = clone.commit("t", "host edit").unwrap();

let outcomes = clone.ws_harvest(None, "t", None).unwrap();
let merged = match outcomes.as_slice() {
[WsHarvestOutcome::Landed { merged_tip, .. }] => *merged_tip,
other => panic!("expected a clean landing, got {other:?}"),
};
let snap = clone.snapshot(&merged).unwrap();
assert_eq!(snap.parents.len(), 2);
assert_eq!(snap.parents[0], host_tip);
assert_eq!(
std::fs::read(fx.clone_root.join("src/a.txt")).unwrap(),
b"ONE\ntwo\nTHREE\n"
);
assert_eq!(dir_id(&clone, &merged, "docs"), docs, "docs is unchanged");
assert!(!has(&clone, &docs), "and was never read or fetched");
assert!(!fx.clone_root.join("docs").exists());
assert!(clone.ws_session().unwrap().is_none(), "the session ended");
drop(clone);
fx.cleanup();
}

/// Both sides edit the same line: the workspace falls back to a branch and
/// the landing branch is untouched.
#[test]
fn harvest_conflict_falls_back_to_a_branch() {
let fx = Fx::origin("ws-conflict", |_| {});
let clone = fx.clone(false);
let session = clone.ws_fork(1, "t", None).unwrap();
std::fs::write(session.workspaces[0].dir.join("src/a.txt"), SRC_FIRST).unwrap();
std::fs::write(fx.clone_root.join("src/a.txt"), b"uno\ntwo\nthree\n").unwrap();
let host_tip = clone.commit("t", "host edit").unwrap();

let outcomes = clone.ws_harvest(None, "t", None).unwrap();
match outcomes.as_slice() {
[WsHarvestOutcome::FallbackBranch { branch, .. }] => {
assert_eq!(branch, "work-1");
}
other => panic!("expected a fallback branch, got {other:?}"),
}
assert!(refs::read_branch_tip(clone.layout(), "work-1")
.unwrap()
.is_some());
assert_eq!(
refs::read_branch_tip(clone.layout(), "main").unwrap(),
Some(host_tip),
"main did not move"
);
assert!(!clone.merge_in_progress());
drop(clone);
fx.cleanup();
}

/// An untouched workspace harvests as unchanged, with no branch minted.
#[test]
fn harvest_of_an_untouched_workspace_is_unchanged() {
let fx = Fx::origin("ws-unchanged", |_| {});
let clone = fx.clone(false);
clone.ws_fork(1, "t", None).unwrap();
let outcomes = clone.ws_harvest(None, "t", None).unwrap();
assert!(matches!(
outcomes.as_slice(),
[WsHarvestOutcome::Unchanged { .. }]
));
assert!(refs::read_branch_tip(clone.layout(), "work-1")
.unwrap()
.is_none());
drop(clone);
fx.cleanup();
}

fn work_opts(cmd: &[&str], scratch: &std::path::Path) -> WorkOptions {
WorkOptions {
agents: 1,
base_name: "agent".into(),
cmd: cmd.iter().map(|s| s.to_string()).collect(),
author: "t".into(),
message: None,
identity: None,
with_secrets: false,
session_root: Some(scratch.join("session")),
}
}

/// `sc work` agents see the view only, and what they commit is grafted onto
/// the base's out-of-view subtrees without reading them.
#[test]
fn work_agents_see_the_view_and_harvest_without_reading_the_rest() {
let fx = Fx::origin("work-partial", |_| {});
let clone = fx.clone(false);
let base = refs::read_branch_tip(clone.layout(), "main")
.unwrap()
.unwrap();
let docs = dir_id(&clone, &base, "docs");
let scratch = std::env::temp_dir().join(format!("scl-work-partial-{}", std::process::id()));
let _ = std::fs::remove_dir_all(&scratch);
std::fs::create_dir_all(&scratch).unwrap();

// The agent proves it cannot see docs/ and edits a file in the view.
let outcomes = clone
.work(work_opts(
&["sh", "-c", "test ! -e docs && echo agent >> src/a.txt"],
&scratch,
))
.unwrap();
assert_eq!(outcomes.len(), 1);
assert_eq!(outcomes[0].agent_exit, Some(0));
let tip = match &outcomes[0].harvest {
Ok(crate::workspace::HarvestResult::Committed(id)) => *id,
other => panic!("expected a committed harvest, got {other:?}"),
};
assert_eq!(
refs::read_branch_tip(clone.layout(), "agent-1").unwrap(),
Some(tip)
);
assert_eq!(dir_id(&clone, &tip, "docs"), docs, "docs is carried");
assert!(!has(&clone, &docs), "and was never read or fetched");
assert!(!scratch.join("session").exists(), "no session residue");
std::fs::remove_dir_all(&scratch).unwrap();
drop(clone);
fx.cleanup();
}

/// A non-lazy clone whose HEAD view holds a gap: fork and `sc work` fail with
/// the gap error before any session state or checkout exists.
#[test]
fn fork_and_work_refuse_a_view_gap_before_writing_anything() {
let fx = Fx::origin("ws-gap", |_| {});
let clone = fx.clone(false);
// The origin adds src/copy.md with the bytes of docs/a.md. The clone never
// fetched that blob (docs/ is outside its filter), so after a fetch an
// in-filter object is absent. Its main is pointed at the new tip.
std::fs::write(fx.origin_root.join("src/copy.md"), b"a\n").unwrap();
fx.origin
.commit("t", "adds a src file sharing a docs blob")
.unwrap();
clone.fetch("origin").unwrap();
let tip = refs::resolve_tip(clone.layout(), "origin/main")
.unwrap()
.unwrap();
refs::write_branch_tip(clone.layout(), "main", &tip).unwrap();
assert!(
!has(&clone, &crate::partial_merge::blob_id(b"a\n")),
"premise: a gap"
);

let err = clone.ws_fork(1, "t", None).unwrap_err();
assert!(
matches!(err, crate::error::Error::GapInView { .. }),
"got {err:?}"
);
assert!(clone.ws_session().unwrap().is_none());
assert!(!clone.layout().dot_sc.join("ws").exists(), "no session dir");

let scratch = std::env::temp_dir().join(format!("scl-work-gap-{}", std::process::id()));
let _ = std::fs::remove_dir_all(&scratch);
std::fs::create_dir_all(&scratch).unwrap();
let err = clone.work(work_opts(&["true"], &scratch)).unwrap_err();
assert!(
matches!(err, crate::error::Error::GapInView { .. }),
"got {err:?}"
);
assert!(!scratch.join("session").exists(), "no session residue");
std::fs::remove_dir_all(&scratch).unwrap();
drop(clone);
fx.cleanup();
}

/// A probe that cannot be answered (the host moved a protected region the
/// clone does not hold) fails the harvest, and must not leave a candidate
/// `work-<i>` branch behind: a retry would mint another one.
#[test]
fn a_failing_probe_leaves_no_candidate_branch() {
let (_sk, pk) = scl_crypto::generate_keypair();
let fx = crate::partial_merge::protected_origin("ws-probe", &pk);
let b1 = fx.origin_branch("b1", &[("vault/s.txt", b"L1\nl2\nl3\n")]);
let clone = fx.clone(false);
let session = clone.ws_fork(1, "t", None).unwrap();
std::fs::write(session.workspaces[0].dir.join("src/a.txt"), SRC_FIRST).unwrap();
// The host fast-forwards to a commit that changed the protected vault/,
// which the clone does not hold and cannot fetch.
clone.merge("origin/b1", "t").unwrap();
assert_eq!(
refs::read_branch_tip(clone.layout(), "main").unwrap(),
Some(b1)
);

let err = clone.ws_harvest(None, "t", None).unwrap_err();
eprintln!("probe error: {err:?}");
assert!(
refs::read_branch_tip(clone.layout(), "work-1")
.unwrap()
.is_none(),
"no candidate branch may survive a failed harvest ({err:?})"
);
assert!(
clone.ws_session().unwrap().is_some(),
"the workspace stays live"
);
assert_eq!(
refs::read_branch_tip(clone.layout(), "main").unwrap(),
Some(b1)
);
clone.ws_abandon(None).unwrap();
drop(clone);
fx.cleanup();
}
Loading
Loading