1use std::collections::HashSet;
2use std::fs::OpenOptions;
3use std::path::{Path, PathBuf};
4
5use crate::error::NbError;
6use crate::gate;
7use crate::git;
8use crate::types::{CommitOutcome, OpOutcome};
9
10use super::apply::{OpMeta, PlanEffects, validate_and_apply_virtual};
11use super::index::{
12 PendingIndexEdit, acquire_index_lock, apply_index_edits, index_id_on_disk,
13 index_rel_for_folder, is_index_rel, numeric_selector, reap_stale_index_lock,
14 split_folder_basename,
15};
16use super::plan::annotate_plan_index;
17use super::virtual_tree::{
18 VirtualNode, VirtualTree, normalize_rel, parent_path, refuse_symlink_ancestors,
19};
20
21use super::plan::Transaction;
22
23impl Transaction {
24 pub async fn commit(self) -> Result<CommitOutcome, NbError> {
26 let notebook_root = self
29 .client
30 .show_notebook_path_unguarded(Some(&self.notebook))
31 .await?;
32 let gate_key = gate::git_common_dir_realpath(¬ebook_root)?;
33 let _hold = gate::acquire_notebook(gate_key, self.gate_timeout, false).await?;
34
35 reap_stale_index_lock(¬ebook_root, self.gate_timeout);
38
39 if git::notebook_is_dirty(¬ebook_root)? {
40 return Err(NbError::DirtyBaseline {
41 guidance: "commit or clean the notebook worktree/index before Transaction::commit"
42 .into(),
43 });
44 }
45
46 let pre_revision = git::notebook_head(¬ebook_root)?;
47 if self.plan.is_empty() {
48 return Ok(CommitOutcome {
49 commit_created: false,
50 revision_id: None,
51 pre_revision,
52 ops: Vec::new(),
53 });
54 }
55
56 let ignored_existing: HashSet<String> = git::list_ignored_paths(¬ebook_root)?
57 .into_iter()
58 .map(|p| normalize_rel(&p))
59 .collect();
60 let mut tree = VirtualTree::from_disk(¬ebook_root)?;
61 let mut op_meta: Vec<OpMeta> = Vec::with_capacity(self.plan.len());
62 let mut effects = PlanEffects::default();
63 let snapshot_keys: HashSet<String> = tree.nodes.keys().cloned().collect();
66
67 for (index, op) in self.plan.iter().enumerate() {
68 match validate_and_apply_virtual(
69 &self.notebook,
70 ¬ebook_root,
71 &mut tree,
72 &ignored_existing,
73 op,
74 index,
75 &mut effects,
76 ) {
77 Ok(meta) => op_meta.push(meta),
78 Err(err) => {
79 return Err(annotate_plan_index(err, index as u32));
80 }
81 }
82 }
83
84 #[cfg(feature = "testing")]
85 if std::env::var_os("NB_API_SIMULATE_EXTERNAL_WRITER").is_some() {
86 simulate_external_writer(¬ebook_root)?;
90 }
91
92 let baseline_on_disk: HashSet<String> = {
95 let mut s: HashSet<String> = git::list_notebook_paths(¬ebook_root)?
96 .into_iter()
97 .map(|p| normalize_rel(&p))
98 .collect();
99 s.extend(ignored_existing.iter().cloned());
100 s
101 };
102
103 let mut force_paths: Vec<String> = tree
108 .nodes
109 .iter()
110 .filter_map(|(p, n)| match n {
111 VirtualNode::File(_) => Some(p.clone()),
112 VirtualNode::Folder => None,
113 })
114 .collect();
115 for meta in &op_meta {
116 for edit in &meta.index_edits {
117 if !force_paths.iter().any(|p| p == &edit.file_rel) {
118 force_paths.push(edit.file_rel.clone());
119 }
120 }
121 }
122
123 let baseline_dirs = existing_dirs_under(¬ebook_root);
126
127 let apply_result = async {
133 materialize_tree(¬ebook_root, &tree, &effects, &snapshot_keys)?;
134 let mut pending: Vec<(u32, PendingIndexEdit)> = Vec::new();
135 for (i, meta) in op_meta.iter().enumerate() {
136 for edit in &meta.index_edits {
137 pending.push((i as u32, edit.clone()));
138 }
139 }
140 let placements = if pending.is_empty() {
141 Vec::new()
142 } else {
143 let _lock = acquire_index_lock(¬ebook_root, self.gate_timeout).await?;
144 let placements = apply_index_edits(¬ebook_root, &pending, self.gate_timeout)?;
145 drop(_lock);
146 placements
147 };
148 let created = git::notebook_commit_all(
149 ¬ebook_root,
150 &format!("nb-api transaction ({} ops)", self.plan.len()),
151 &force_paths,
152 )?;
153 Ok::<_, NbError>((created, placements))
154 }
155 .await;
156
157 match apply_result {
158 Ok((created, placements)) => {
159 let revision_id = if created {
160 match git::notebook_head(¬ebook_root) {
161 Ok(head) => Some(head),
162 Err(_) => {
163 return Err(NbError::IndeterminateCommit {
164 pre_revision,
165 post_revision_observed: None,
166 guidance: "git commit may have succeeded but HEAD could not be re-read; do not retry blindly".into(),
167 });
168 }
169 }
170 } else {
171 None
172 };
173 let ops = op_meta
174 .into_iter()
175 .enumerate()
176 .map(|(i, meta)| {
177 let (selector, numeric_id) =
185 match placements.iter().rev().find(|p| p.op_index == i as u32) {
186 Some(p) => (
187 Some(numeric_selector(&self.notebook, &p.folder, p.id)),
188 Some(p.id),
189 ),
190 None => (
191 meta.selector,
192 meta.path
193 .as_deref()
194 .and_then(|p| index_id_on_disk(¬ebook_root, p)),
195 ),
196 };
197 OpOutcome {
198 index: i as u32,
199 path: meta.path,
200 selector,
201 numeric_id,
202 noop: meta.noop,
203 fingerprint: meta.fingerprint,
204 }
205 })
206 .collect();
207 Ok(CommitOutcome {
208 commit_created: created,
209 revision_id,
210 pre_revision,
211 ops,
212 })
213 }
214 Err(err) => {
215 let post = git::notebook_head(¬ebook_root).ok();
216 if post.as_deref().is_some_and(|h| h != pre_revision.as_str()) {
217 return Err(NbError::IndeterminateCommit {
218 pre_revision,
219 post_revision_observed: post,
220 guidance: "checkpoint may have completed; re-read HEAD/status and do not retry the same plan blindly".into(),
221 });
222 }
223 let owned_new: Vec<String> = force_paths
228 .into_iter()
229 .filter(|p| !baseline_on_disk.contains(p))
230 .filter(|p| !baseline_dirs.contains(p))
231 .collect();
232 match try_restore(¬ebook_root, &pre_revision, &owned_new, &baseline_dirs) {
233 Ok(()) => Err(err),
234 Err(recovery) => Err(recovery),
235 }
236 }
237 }
238 }
239}
240
241fn existing_dirs_under(notebook_root: &Path) -> HashSet<String> {
244 let mut dirs = HashSet::new();
245 fn walk(base: &Path, rel: &Path, out: &mut HashSet<String>) {
246 let entries = match std::fs::read_dir(base) {
247 Ok(e) => e,
248 Err(_) => return,
249 };
250 for entry in entries.flatten() {
251 let name = entry.file_name();
252 if name == ".git" {
253 continue;
254 }
255 let Ok(ft) = entry.file_type() else {
256 continue;
257 };
258 if ft.is_symlink() || !ft.is_dir() {
260 continue;
261 }
262 let child_rel = if rel.as_os_str().is_empty() {
263 PathBuf::from(&name)
264 } else {
265 rel.join(&name)
266 };
267 let key = child_rel.to_string_lossy().replace('\\', "/");
268 out.insert(key);
269 walk(&entry.path(), &child_rel, out);
270 }
271 }
272 walk(notebook_root, Path::new(""), &mut dirs);
273 dirs
274}
275
276fn try_restore(
277 notebook_root: &Path,
278 pre_revision: &str,
279 remove_new_owned: &[String],
280 baseline_dirs: &HashSet<String>,
281) -> Result<(), NbError> {
282 if let Err(e) = git::notebook_reset_clean(notebook_root, pre_revision) {
283 let post = git::notebook_head(notebook_root).ok();
284 let status = git::notebook_status_porcelain(notebook_root).ok();
285 return Err(NbError::RecoveryRequired {
286 pre_revision: pre_revision.to_string(),
287 post_revision_observed: post,
288 status_observed: status,
289 preserved_paths: Some(remove_new_owned.to_vec()),
290 guidance: format!(
291 "cleanup after failed commit could not be verified; inspect HEAD/status before retry. underlying: {e}"
292 ),
293 });
294 }
295 for d in baseline_dirs {
299 let abs = notebook_root.join(d);
300 if !abs.exists()
301 && let Err(e) = std::fs::create_dir_all(&abs)
302 {
303 return Err(NbError::RecoveryRequired {
304 pre_revision: pre_revision.to_string(),
305 post_revision_observed: git::notebook_head(notebook_root).ok(),
306 status_observed: git::notebook_status_porcelain(notebook_root).ok(),
307 preserved_paths: Some(vec![d.clone()]),
308 guidance: format!(
309 "failed to restore baseline directory `{d}` after cleanup; do not retry blindly. underlying: {e}"
310 ),
311 });
312 }
313 }
314 let mut remaining = Vec::new();
317 for rel in remove_new_owned {
318 let abs = notebook_root.join(rel);
319 match std::fs::symlink_metadata(&abs) {
320 Ok(meta) if meta.file_type().is_symlink() || meta.is_file() => {
321 if let Err(e) = std::fs::remove_file(&abs) {
322 remaining.push(format!("{rel} ({e})"));
323 }
324 }
325 Ok(meta) if meta.is_dir() => {
326 if let Err(e) = std::fs::remove_dir_all(&abs) {
327 remaining.push(format!("{rel} ({e})"));
328 }
329 }
330 Ok(_) => {}
331 Err(e) if e.kind() == std::io::ErrorKind::NotFound => {}
332 Err(e) => remaining.push(format!("{rel} ({e})")),
333 }
334 if let Some(parent) = parent_path(rel) {
337 let mut cur = parent;
338 loop {
339 if baseline_dirs.contains(&cur) {
340 break;
341 }
342 let p = notebook_root.join(&cur);
343 match std::fs::remove_dir(&p) {
344 Ok(()) => {}
345 Err(_) => break,
346 }
347 match parent_path(&cur) {
348 Some(next) => cur = next,
349 None => break,
350 }
351 }
352 }
353 }
354 if !remaining.is_empty() {
355 return Err(NbError::RecoveryRequired {
356 pre_revision: pre_revision.to_string(),
357 post_revision_observed: git::notebook_head(notebook_root).ok(),
358 status_observed: git::notebook_status_porcelain(notebook_root).ok(),
359 preserved_paths: Some(remaining),
360 guidance: "failed to remove transaction-owned outputs after aborted commit; do not retry blindly".into(),
361 });
362 }
363 let mut still_present = Vec::new();
365 for rel in remove_new_owned {
366 if notebook_root.join(rel).exists() {
367 still_present.push(rel.clone());
368 }
369 }
370 let head = match restore_verify_head(notebook_root) {
371 Ok(h) => h,
372 Err(e) => {
373 return Err(NbError::RecoveryRequired {
374 pre_revision: pre_revision.to_string(),
375 post_revision_observed: None,
376 status_observed: git::notebook_status_porcelain(notebook_root).ok(),
377 preserved_paths: if still_present.is_empty() {
378 None
379 } else {
380 Some(still_present)
381 },
382 guidance: format!(
383 "cleanup ran but HEAD re-read failed during verification; do not retry blindly. underlying: {e}"
384 ),
385 });
386 }
387 };
388 let dirty = match restore_verify_dirty(notebook_root) {
389 Ok(d) => d,
390 Err(e) => {
391 return Err(NbError::RecoveryRequired {
392 pre_revision: pre_revision.to_string(),
393 post_revision_observed: Some(head),
394 status_observed: git::notebook_status_porcelain(notebook_root).ok(),
395 preserved_paths: if still_present.is_empty() {
396 None
397 } else {
398 Some(still_present)
399 },
400 guidance: format!(
401 "cleanup ran but dirty-status check failed during verification; do not retry blindly. underlying: {e}"
402 ),
403 });
404 }
405 };
406 if head != pre_revision || dirty || !still_present.is_empty() {
407 return Err(NbError::RecoveryRequired {
408 pre_revision: pre_revision.to_string(),
409 post_revision_observed: Some(head),
410 status_observed: git::notebook_status_porcelain(notebook_root).ok(),
411 preserved_paths: if still_present.is_empty() {
412 None
413 } else {
414 Some(still_present)
415 },
416 guidance:
417 "cleanup ran but HEAD/status/owned-path verification failed; do not retry blindly"
418 .into(),
419 });
420 }
421 Ok(())
422}
423
424fn restore_verify_head(notebook_root: &Path) -> Result<String, NbError> {
426 #[cfg(feature = "testing")]
427 if std::env::var_os("NB_API_FAIL_RESTORE_HEAD").is_some() {
428 return Err(NbError::CommandFailed {
429 command: "nb-api://fail-restore-head".into(),
430 stderr: "injected HEAD verify failure for rollback tests".into(),
431 exit_code: Some(1),
432 });
433 }
434 git::notebook_head(notebook_root)
435}
436
437fn restore_verify_dirty(notebook_root: &Path) -> Result<bool, NbError> {
439 #[cfg(feature = "testing")]
440 if std::env::var_os("NB_API_FAIL_RESTORE_DIRTY").is_some() {
441 return Err(NbError::CommandFailed {
442 command: "nb-api://fail-restore-dirty".into(),
443 stderr: "injected dirty-status verify failure for rollback tests".into(),
444 exit_code: Some(1),
445 });
446 }
447 git::notebook_is_dirty(notebook_root)
448}
449
450#[cfg(feature = "testing")]
459fn simulate_external_writer(notebook_root: &Path) -> Result<(), NbError> {
460 use std::io::Write as _;
461 let (folder, name) = match std::env::var("NB_API_SIMULATE_EXTERNAL_SAME_PATH") {
462 Ok(rel) => {
463 let (folder, basename) = split_folder_basename(&normalize_rel(&rel));
464 (folder, basename)
465 }
466 Err(_) => (String::new(), format!("external-{}.md", std::process::id())),
467 };
468 let rel = if folder.is_empty() {
469 name.clone()
470 } else {
471 format!("{folder}/{name}")
472 };
473 if !folder.is_empty() {
474 std::fs::create_dir_all(notebook_root.join(&folder)).map_err(|e| NbError::Io {
475 path: notebook_root.join(&folder),
476 source: e.into(),
477 })?;
478 }
479 std::fs::write(notebook_root.join(&rel), b"# External\n\nexternal body\n").map_err(|e| {
480 NbError::Io {
481 path: notebook_root.join(&rel),
482 source: e.into(),
483 }
484 })?;
485 let index_abs = notebook_root.join(index_rel_for_folder(&folder));
486 let mut f = OpenOptions::new()
487 .create(true)
488 .append(true)
489 .open(&index_abs)
490 .map_err(|e| NbError::Io {
491 path: index_abs.clone(),
492 source: e.into(),
493 })?;
494 writeln!(f, "{name}").map_err(|e| NbError::Io {
495 path: index_abs.clone(),
496 source: e.into(),
497 })?;
498 drop(f);
499 git::notebook_commit_all(
500 notebook_root,
501 "external writer",
502 &[rel, index_rel_for_folder(&folder)],
503 )?;
504 Ok(())
505}
506
507fn materialize_tree(
520 root: &Path,
521 tree: &VirtualTree,
522 effects: &PlanEffects,
523 snapshot_keys: &HashSet<String>,
524) -> Result<(), NbError> {
525 for rel in tree.nodes.keys() {
528 refuse_symlink_ancestors(root, rel)?;
529 }
530
531 let mut removed: Vec<&String> = effects.removed.iter().collect();
533 removed.sort();
534 removed.dedup();
535 for rel in removed {
536 let key = normalize_rel(rel);
537 let abs = root.join(&key);
538 let meta = match std::fs::symlink_metadata(&abs) {
539 Ok(m) => m,
540 Err(e) if e.kind() == std::io::ErrorKind::NotFound => continue,
541 Err(e) => {
542 return Err(NbError::Io {
543 path: abs,
544 source: e.into(),
545 });
546 }
547 };
548 if meta.file_type().is_symlink() {
549 return Err(NbError::UnsupportedStructure {
550 reason: format!("refusing to materialize through symlink `{key}`"),
551 });
552 }
553 if meta.is_file() && !matches!(tree.nodes.get(&key), Some(VirtualNode::File(_))) {
554 std::fs::remove_file(&abs).map_err(|e| NbError::Io {
555 path: abs,
556 source: e.into(),
557 })?;
558 }
559 }
560 let mut mkdirs: Vec<&String> = effects.mkdirs.iter().collect();
562 mkdirs.sort();
563 mkdirs.dedup();
564 for rel in mkdirs {
565 let key = normalize_rel(rel);
566 let abs = root.join(&key);
567 refuse_symlink_ancestors(root, &key)?;
568 std::fs::create_dir_all(&abs).map_err(|e| NbError::Io {
569 path: abs.clone(),
570 source: e.into(),
571 })?;
572 }
573 let mut written: Vec<&String> = effects
575 .written
576 .iter()
577 .filter(|rel| !is_index_rel(rel))
578 .collect();
579 written.sort();
580 written.dedup();
581 let created: HashSet<&String> = effects.created.iter().collect();
582 for rel in written {
583 let key = normalize_rel(rel);
584 let created_contains = created.contains(rel);
585 let Some(VirtualNode::File(bytes)) = tree.nodes.get(&key) else {
586 return Err(NbError::ValidationError {
587 reason: format!("plan effect `{key}` has no file content"),
588 location: None,
589 });
590 };
591 let abs = root.join(&key);
592 refuse_symlink_ancestors(root, &key)?;
594 if let Ok(meta) = std::fs::symlink_metadata(&abs) {
595 if meta.file_type().is_symlink() {
596 return Err(NbError::UnsupportedStructure {
597 reason: format!("refusing to write through symlink `{key}`"),
598 });
599 }
600 if created_contains && !snapshot_keys.contains(&key) {
604 return Err(NbError::PathCollision {
605 path: key,
606 plan_index: None,
607 });
608 }
609 }
610 if let Some(parent) = abs.parent() {
611 std::fs::create_dir_all(parent).map_err(|e| NbError::Io {
612 path: parent.to_path_buf(),
613 source: e.into(),
614 })?;
615 }
616 std::fs::write(&abs, bytes).map_err(|e| NbError::Io {
617 path: abs,
618 source: e.into(),
619 })?;
620 }
621 Ok(())
622}