Skip to main content

nb_api/
transaction.rs

1//! Collect-then-commit [`Transaction`] plan and apply engine.
2
3use std::collections::{HashMap, HashSet};
4use std::fs::OpenOptions;
5use std::io::Write;
6use std::path::{Path, PathBuf};
7use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
8
9use crate::NbClient;
10use crate::error::NbError;
11use crate::fingerprint::{self, Fingerprint};
12use crate::gate;
13use crate::git;
14use crate::lines::{
15    apply_line_edits, apply_substring, require_contiguous_body, splice_body, splice_title,
16};
17use crate::parser::{DocumentKind, NoteDocument, ParseContext, parse};
18use crate::types::{CommitOutcome, LineEdit, NoteTarget, Occurrence, OpOutcome};
19
20/// In-memory plan bound to one notebook. Drop discards; no begin/rollback.
21pub struct Transaction {
22    client: NbClient,
23    notebook: String,
24    plan: Vec<PlanOp>,
25    gate_timeout: Duration,
26}
27
28#[derive(Debug, Clone)]
29enum PlanOp {
30    AddNote {
31        path: String,
32        title: Option<String>,
33        content: String,
34        tags: Vec<String>,
35    },
36    AddTodo {
37        path: String,
38        title: String,
39        description: Option<String>,
40        tasks: Vec<String>,
41        tags: Vec<String>,
42    },
43    AddBookmark {
44        path: String,
45        url: String,
46        title: Option<String>,
47        tags: Vec<String>,
48        comment: Option<String>,
49    },
50    AddFolder {
51        path: String,
52    },
53    DeleteNote {
54        target: NoteTarget,
55    },
56    MoveNote {
57        target: NoteTarget,
58        destination: String,
59    },
60    MarkTaskDone {
61        target: NoteTarget,
62        task_number: Option<u32>,
63    },
64    UnmarkTaskDone {
65        target: NoteTarget,
66        task_number: Option<u32>,
67    },
68    ReplaceNoteBody {
69        target: NoteTarget,
70        new_body: String,
71        fingerprint: Fingerprint,
72    },
73    EditNoteSubstring {
74        target: NoteTarget,
75        pattern: String,
76        replacement: String,
77        occurrence: Occurrence,
78        expected_count: u32,
79        fingerprint: Option<Fingerprint>,
80    },
81    EditNoteLines {
82        target: NoteTarget,
83        edits: Vec<LineEdit>,
84    },
85    RetitleNote {
86        target: NoteTarget,
87        title: String,
88    },
89    EditNoteTags {
90        target: NoteTarget,
91        add: Vec<String>,
92        remove: Vec<String>,
93    },
94}
95
96#[derive(Debug, Clone)]
97enum VirtualNode {
98    File(Vec<u8>),
99    Folder,
100}
101
102struct VirtualTree {
103    /// Notebook-relative paths using `/` separators.
104    nodes: HashMap<String, VirtualNode>,
105}
106
107impl VirtualTree {
108    fn from_disk(root: &Path) -> Result<Self, NbError> {
109        let mut nodes = HashMap::new();
110        let paths = git::list_notebook_paths(root)?;
111        for rel in paths {
112            let key = normalize_rel(&rel);
113            let abs = root.join(&rel);
114            let meta = std::fs::symlink_metadata(&abs).map_err(|e| NbError::Io {
115                path: abs.clone(),
116                source: e.into(),
117            })?;
118            if meta.file_type().is_symlink() {
119                return Err(NbError::UnsupportedStructure {
120                    reason: format!(
121                        "notebook path `{key}` is a symlink; transactions refuse symlink snapshot/materialization"
122                    ),
123                });
124            }
125            if meta.is_dir() {
126                nodes.insert(key, VirtualNode::Folder);
127            } else if meta.is_file() {
128                let bytes = std::fs::read(&abs).map_err(|e| NbError::Io {
129                    path: abs,
130                    source: e.into(),
131                })?;
132                // Non-empty directories may be absent from the path list
133                // (only their children are listed); chain the parents so a
134                // create/move onto an existing directory path collides
135                // instead of materializing a file over the directory.
136                if let Some(parent) = parent_path(&key) {
137                    let mut acc = String::new();
138                    for part in parent.split('/').filter(|p| !p.is_empty()) {
139                        if !acc.is_empty() {
140                            acc.push('/');
141                        }
142                        acc.push_str(part);
143                        nodes.entry(acc.clone()).or_insert(VirtualNode::Folder);
144                    }
145                }
146                nodes.insert(key, VirtualNode::File(bytes));
147            }
148        }
149        Ok(Self { nodes })
150    }
151
152    fn exists(&self, path: &str) -> bool {
153        self.nodes.contains_key(path)
154    }
155
156    fn get_file(&self, path: &str) -> Option<&[u8]> {
157        match self.nodes.get(path) {
158            Some(VirtualNode::File(b)) => Some(b),
159            _ => None,
160        }
161    }
162
163    fn insert_file(&mut self, path: String, bytes: Vec<u8>) {
164        // Ensure parent folders exist virtually.
165        if let Some(parent) = parent_path(&path) {
166            self.ensure_folder_chain(&parent);
167        }
168        self.nodes.insert(path, VirtualNode::File(bytes));
169    }
170
171    fn insert_folder(&mut self, path: String) {
172        self.ensure_folder_chain(&path);
173        self.nodes.insert(path, VirtualNode::Folder);
174    }
175
176    fn ensure_folder_chain(&mut self, path: &str) {
177        let mut acc = String::new();
178        for part in path.split('/').filter(|p| !p.is_empty()) {
179            if !acc.is_empty() {
180                acc.push('/');
181            }
182            acc.push_str(part);
183            self.nodes.entry(acc.clone()).or_insert(VirtualNode::Folder);
184        }
185    }
186
187    fn remove(&mut self, path: &str) {
188        self.nodes.remove(path);
189    }
190
191    fn rename(&mut self, from: &str, to: &str) -> Result<(), NbError> {
192        let node = self.nodes.remove(from).ok_or_else(|| NbError::NotFound {
193            selector: from.to_string(),
194        })?;
195        if let Some(parent) = parent_path(to) {
196            self.ensure_folder_chain(&parent);
197        }
198        self.nodes.insert(to.to_string(), node);
199        Ok(())
200    }
201}
202
203impl Transaction {
204    pub(crate) fn new(client: NbClient, notebook: String, gate_timeout: Duration) -> Self {
205        Self {
206            client,
207            notebook,
208            plan: Vec::new(),
209            gate_timeout,
210        }
211    }
212
213    pub fn add_note(
214        &mut self,
215        path: &str,
216        title: Option<&str>,
217        content: &str,
218        tags: &[String],
219    ) -> Result<(), NbError> {
220        let path = validate_create_path(path, true)?;
221        if let Some(t) = title
222            && let Some(heading) = crate::validate::detect_duplicate_title_heading(t, content)
223        {
224            return Err(NbError::DuplicateTitleHeading {
225                title: t.to_string(),
226                heading,
227            });
228        }
229        self.plan.push(PlanOp::AddNote {
230            path,
231            title: title.map(str::to_string),
232            content: content.to_string(),
233            tags: tags.to_vec(),
234        });
235        Ok(())
236    }
237
238    pub fn add_todo(
239        &mut self,
240        path: &str,
241        title: &str,
242        description: Option<&str>,
243        tasks: &[String],
244        tags: &[String],
245    ) -> Result<(), NbError> {
246        let path = validate_create_path(path, true)?;
247        if title.trim().is_empty() {
248            return Err(NbError::ValidationError {
249                reason: "todo title must not be empty".into(),
250                location: None,
251            });
252        }
253        self.plan.push(PlanOp::AddTodo {
254            path,
255            title: title.to_string(),
256            description: description.map(str::to_string),
257            tasks: tasks.to_vec(),
258            tags: tags.to_vec(),
259        });
260        Ok(())
261    }
262
263    pub fn add_bookmark(
264        &mut self,
265        path: &str,
266        url: &str,
267        title: Option<&str>,
268        tags: &[String],
269        comment: Option<&str>,
270    ) -> Result<(), NbError> {
271        let path = validate_create_path(path, true)?;
272        if url.trim().is_empty() {
273            return Err(NbError::ValidationError {
274                reason: "bookmark url must not be empty".into(),
275                location: None,
276            });
277        }
278        self.plan.push(PlanOp::AddBookmark {
279            path,
280            url: url.to_string(),
281            title: title.map(str::to_string),
282            tags: tags.to_vec(),
283            comment: comment.map(str::to_string),
284        });
285        Ok(())
286    }
287
288    pub fn add_folder(&mut self, path: &str) -> Result<(), NbError> {
289        let path = validate_create_path(path, false)?;
290        self.plan.push(PlanOp::AddFolder { path });
291        Ok(())
292    }
293
294    pub fn delete_note(&mut self, target: NoteTarget) -> Result<(), NbError> {
295        validate_target(&target)?;
296        self.plan.push(PlanOp::DeleteNote { target });
297        Ok(())
298    }
299
300    pub fn move_note(&mut self, target: NoteTarget, destination: &str) -> Result<(), NbError> {
301        validate_target(&target)?;
302        crate::validate::validate_destination(destination)?;
303        // Preserve a trailing slash: `foo/` means "into folder foo" (basename
304        // kept). `normalize_rel` trims slashes, so re-attach the marker for
305        // `resolve_move_destination`.
306        let into_folder = destination.trim_end().ends_with('/');
307        let mut destination = normalize_rel(destination);
308        if destination.is_empty() || destination.contains("..") {
309            return Err(NbError::ValidationError {
310                reason: "invalid move destination".into(),
311                location: None,
312            });
313        }
314        if into_folder {
315            destination.push('/');
316        }
317        self.plan.push(PlanOp::MoveNote {
318            target,
319            destination,
320        });
321        Ok(())
322    }
323
324    pub fn mark_task_done(
325        &mut self,
326        target: NoteTarget,
327        task_number: Option<u32>,
328    ) -> Result<(), NbError> {
329        validate_target(&target)?;
330        self.plan.push(PlanOp::MarkTaskDone {
331            target,
332            task_number,
333        });
334        Ok(())
335    }
336
337    pub fn unmark_task_done(
338        &mut self,
339        target: NoteTarget,
340        task_number: Option<u32>,
341    ) -> Result<(), NbError> {
342        validate_target(&target)?;
343        self.plan.push(PlanOp::UnmarkTaskDone {
344            target,
345            task_number,
346        });
347        Ok(())
348    }
349
350    pub fn replace_note_body(
351        &mut self,
352        target: NoteTarget,
353        new_body: &str,
354        fingerprint: Fingerprint,
355    ) -> Result<(), NbError> {
356        validate_target(&target)?;
357        self.plan.push(PlanOp::ReplaceNoteBody {
358            target,
359            new_body: new_body.to_string(),
360            fingerprint,
361        });
362        Ok(())
363    }
364
365    pub fn edit_note_substring(
366        &mut self,
367        target: NoteTarget,
368        pattern: &str,
369        replacement: &str,
370        occurrence: Occurrence,
371        expected_count: u32,
372        fingerprint: Option<Fingerprint>,
373    ) -> Result<(), NbError> {
374        validate_target(&target)?;
375        if pattern.is_empty() {
376            return Err(NbError::EmptySubstringPattern);
377        }
378        self.plan.push(PlanOp::EditNoteSubstring {
379            target,
380            pattern: pattern.to_string(),
381            replacement: replacement.to_string(),
382            occurrence,
383            expected_count,
384            fingerprint,
385        });
386        Ok(())
387    }
388
389    pub fn edit_note_lines(
390        &mut self,
391        target: NoteTarget,
392        edits: Vec<LineEdit>,
393    ) -> Result<(), NbError> {
394        validate_target(&target)?;
395        if edits.is_empty() {
396            return Err(NbError::ValidationError {
397                reason: "edit_note_lines requires a non-empty edits batch".into(),
398                location: None,
399            });
400        }
401        self.plan.push(PlanOp::EditNoteLines { target, edits });
402        Ok(())
403    }
404
405    pub fn retitle_note(&mut self, target: NoteTarget, title: &str) -> Result<(), NbError> {
406        validate_target(&target)?;
407        self.plan.push(PlanOp::RetitleNote {
408            target,
409            title: title.to_string(),
410        });
411        Ok(())
412    }
413
414    pub fn edit_note_tags(
415        &mut self,
416        target: NoteTarget,
417        add: &[String],
418        remove: &[String],
419    ) -> Result<(), NbError> {
420        validate_target(&target)?;
421        let add_set: HashSet<&str> = add.iter().map(|s| s.trim_start_matches('#')).collect();
422        for r in remove {
423            let key = r.trim_start_matches('#');
424            if add_set.contains(key) {
425                return Err(NbError::ValidationError {
426                    reason: format!("contradictory tag add/remove for `{key}`"),
427                    location: None,
428                });
429            }
430        }
431        self.plan.push(PlanOp::EditNoteTags {
432            target,
433            add: add.to_vec(),
434            remove: remove.to_vec(),
435        });
436        Ok(())
437    }
438
439    /// Validate-all, apply-all, at most one Git checkpoint.
440    pub async fn commit(self) -> Result<CommitOutcome, NbError> {
441        // Resolve root without invoking `nb` when possible (avoids nb
442        // auto-checkpoint clearing dirty state before the baseline check).
443        let notebook_root = self
444            .client
445            .show_notebook_path_unguarded(Some(&self.notebook))
446            .await?;
447        let gate_key = gate::git_common_dir_realpath(&notebook_root)?;
448        let _hold = gate::acquire_notebook(gate_key, self.gate_timeout, false).await?;
449
450        // A crashed writer may leave its `.nb-api-index.lock` behind; an
451        // untracked lock file reads as dirty, so reap a stale one first.
452        reap_stale_index_lock(&notebook_root, self.gate_timeout);
453
454        if git::notebook_is_dirty(&notebook_root)? {
455            return Err(NbError::DirtyBaseline {
456                guidance: "commit or clean the notebook worktree/index before Transaction::commit"
457                    .into(),
458            });
459        }
460
461        let pre_revision = git::notebook_head(&notebook_root)?;
462        if self.plan.is_empty() {
463            return Ok(CommitOutcome {
464                commit_created: false,
465                revision_id: None,
466                pre_revision,
467                ops: Vec::new(),
468            });
469        }
470
471        let ignored_existing: HashSet<String> = git::list_ignored_paths(&notebook_root)?
472            .into_iter()
473            .map(|p| normalize_rel(&p))
474            .collect();
475        let mut tree = VirtualTree::from_disk(&notebook_root)?;
476        let mut op_meta: Vec<OpMeta> = Vec::with_capacity(self.plan.len());
477        let mut effects = PlanEffects::default();
478        // Disk keys at snapshot time: materialize refuses a planned create
479        // that appears on disk afterwards (external same-path race).
480        let snapshot_keys: HashSet<String> = tree.nodes.keys().cloned().collect();
481
482        for (index, op) in self.plan.iter().enumerate() {
483            match validate_and_apply_virtual(
484                &self.notebook,
485                &notebook_root,
486                &mut tree,
487                &ignored_existing,
488                op,
489                index,
490                &mut effects,
491            ) {
492                Ok(meta) => op_meta.push(meta),
493                Err(err) => {
494                    return Err(annotate_plan_index(err, index as u32));
495                }
496            }
497        }
498
499        #[cfg(feature = "testing")]
500        if std::env::var_os("NB_API_SIMULATE_EXTERNAL_WRITER").is_some() {
501            // Deterministic stand-in for an external `nb add` racing our
502            // snapshot: create AND commit a note this transaction knows
503            // nothing about. Our commit must preserve it (file + index line).
504            simulate_external_writer(&notebook_root)?;
505        }
506
507        // Disk baseline before materialize (for rollback of new owned outputs).
508        // Virtual tree already includes planned ops; disk is still pre-apply.
509        let baseline_on_disk: HashSet<String> = {
510            let mut s: HashSet<String> = git::list_notebook_paths(&notebook_root)?
511                .into_iter()
512                .map(|p| normalize_rel(&p))
513                .collect();
514            s.extend(ignored_existing.iter().cloned());
515            s
516        };
517
518        // Force-stage every final file path so ignore rules cannot drop
519        // transaction-owned outputs (new ignored names, `.gitkeep`, etc.).
520        // `.index` files are applied post-materialize (fresh read under the
521        // index lock) but staged by the same checkpoint, so list them too.
522        let mut force_paths: Vec<String> = tree
523            .nodes
524            .iter()
525            .filter_map(|(p, n)| match n {
526                VirtualNode::File(_) => Some(p.clone()),
527                VirtualNode::Folder => None,
528            })
529            .collect();
530        for meta in &op_meta {
531            for edit in &meta.index_edits {
532                if !force_paths.iter().any(|p| p == &edit.file_rel) {
533                    force_paths.push(edit.file_rel.clone());
534                }
535            }
536        }
537
538        // Directories that already exist before materialize must never be
539        // pruned during rollback (including empty ignored parents).
540        let baseline_dirs = existing_dirs_under(&notebook_root);
541
542        // Materialize non-index files, apply `.index` edits from fresh
543        // on-disk content under `.nb-api-index.lock` (released before git
544        // staging — never held across `git add`/`commit`), then checkpoint.
545        // The lock serializes nb-api writers only; external `nb` writers are
546        // covered by O_APPEND plus post-write selector derivation.
547        let apply_result = async {
548            materialize_tree(&notebook_root, &tree, &effects, &snapshot_keys)?;
549            let mut pending: Vec<(u32, PendingIndexEdit)> = Vec::new();
550            for (i, meta) in op_meta.iter().enumerate() {
551                for edit in &meta.index_edits {
552                    pending.push((i as u32, edit.clone()));
553                }
554            }
555            let placements = if pending.is_empty() {
556                Vec::new()
557            } else {
558                let _lock = acquire_index_lock(&notebook_root, self.gate_timeout).await?;
559                let placements = apply_index_edits(&notebook_root, &pending, self.gate_timeout)?;
560                drop(_lock);
561                placements
562            };
563            let created = git::notebook_commit_all(
564                &notebook_root,
565                &format!("nb-api transaction ({} ops)", self.plan.len()),
566                &force_paths,
567            )?;
568            Ok::<_, NbError>((created, placements))
569        }
570        .await;
571
572        match apply_result {
573            Ok((created, placements)) => {
574                let revision_id = if created {
575                    match git::notebook_head(&notebook_root) {
576                        Ok(head) => Some(head),
577                        Err(_) => {
578                            return Err(NbError::IndeterminateCommit {
579                                pre_revision,
580                                post_revision_observed: None,
581                                guidance: "git commit may have succeeded but HEAD could not be re-read; do not retry blindly".into(),
582                            });
583                        }
584                    }
585                } else {
586                    None
587                };
588                let ops = op_meta
589                    .into_iter()
590                    .enumerate()
591                    .map(|(i, meta)| {
592                        // Creates/moves/deletes carry post-write placements:
593                        // selector becomes the numeric `<folder>/<id>` form.
594                        // A cross-folder move records both a blank (source)
595                        // and an append (destination); the destination
596                        // placement is last, so take the last match.
597                        // All other ops keep the echoed target selector and
598                        // gain a numeric id when the path is indexed.
599                        let (selector, numeric_id) =
600                            match placements.iter().rev().find(|p| p.op_index == i as u32) {
601                                Some(p) => (
602                                    Some(numeric_selector(&self.notebook, &p.folder, p.id)),
603                                    Some(p.id),
604                                ),
605                                None => (
606                                    meta.selector,
607                                    meta.path
608                                        .as_deref()
609                                        .and_then(|p| index_id_on_disk(&notebook_root, p)),
610                                ),
611                            };
612                        OpOutcome {
613                            index: i as u32,
614                            path: meta.path,
615                            selector,
616                            numeric_id,
617                            noop: meta.noop,
618                            fingerprint: meta.fingerprint,
619                        }
620                    })
621                    .collect();
622                Ok(CommitOutcome {
623                    commit_created: created,
624                    revision_id,
625                    pre_revision,
626                    ops,
627                })
628            }
629            Err(err) => {
630                let post = git::notebook_head(&notebook_root).ok();
631                if post.as_deref().is_some_and(|h| h != pre_revision.as_str()) {
632                    return Err(NbError::IndeterminateCommit {
633                        pre_revision,
634                        post_revision_observed: post,
635                        guidance: "checkpoint may have completed; re-read HEAD/status and do not retry the same plan blindly".into(),
636                    });
637                }
638                // Owned outputs that did not exist at baseline must be removed
639                // even when ignored (git clean -fd keeps ignored files).
640                // Baseline directories are never owned outputs: pruning one
641                // would `remove_dir_all` a pre-existing folder.
642                let owned_new: Vec<String> = force_paths
643                    .into_iter()
644                    .filter(|p| !baseline_on_disk.contains(p))
645                    .filter(|p| !baseline_dirs.contains(p))
646                    .collect();
647                match try_restore(&notebook_root, &pre_revision, &owned_new, &baseline_dirs) {
648                    Ok(()) => Err(err),
649                    Err(recovery) => Err(recovery),
650                }
651            }
652        }
653    }
654}
655
656/// All directory paths under the notebook root before materialize (relative,
657/// `/`-separated). Used so rollback never deletes pre-existing dirs.
658fn existing_dirs_under(notebook_root: &Path) -> HashSet<String> {
659    let mut dirs = HashSet::new();
660    fn walk(base: &Path, rel: &Path, out: &mut HashSet<String>) {
661        let entries = match std::fs::read_dir(base) {
662            Ok(e) => e,
663            Err(_) => return,
664        };
665        for entry in entries.flatten() {
666            let name = entry.file_name();
667            if name == ".git" {
668                continue;
669            }
670            let Ok(ft) = entry.file_type() else {
671                continue;
672            };
673            // Do not follow symlinks.
674            if ft.is_symlink() || !ft.is_dir() {
675                continue;
676            }
677            let child_rel = if rel.as_os_str().is_empty() {
678                PathBuf::from(&name)
679            } else {
680                rel.join(&name)
681            };
682            let key = child_rel.to_string_lossy().replace('\\', "/");
683            out.insert(key);
684            walk(&entry.path(), &child_rel, out);
685        }
686    }
687    walk(notebook_root, Path::new(""), &mut dirs);
688    dirs
689}
690
691fn try_restore(
692    notebook_root: &Path,
693    pre_revision: &str,
694    remove_new_owned: &[String],
695    baseline_dirs: &HashSet<String>,
696) -> Result<(), NbError> {
697    if let Err(e) = git::notebook_reset_clean(notebook_root, pre_revision) {
698        let post = git::notebook_head(notebook_root).ok();
699        let status = git::notebook_status_porcelain(notebook_root).ok();
700        return Err(NbError::RecoveryRequired {
701            pre_revision: pre_revision.to_string(),
702            post_revision_observed: post,
703            status_observed: status,
704            preserved_paths: Some(remove_new_owned.to_vec()),
705            guidance: format!(
706                "cleanup after failed commit could not be verified; inspect HEAD/status before retry. underlying: {e}"
707            ),
708        });
709    }
710    // `git clean -fd` can remove empty untracked dirs (including ignored
711    // parents) once staged children are cleared by reset --hard. Restore any
712    // baseline directory that disappeared.
713    for d in baseline_dirs {
714        let abs = notebook_root.join(d);
715        if !abs.exists()
716            && let Err(e) = std::fs::create_dir_all(&abs)
717        {
718            return Err(NbError::RecoveryRequired {
719                pre_revision: pre_revision.to_string(),
720                post_revision_observed: git::notebook_head(notebook_root).ok(),
721                status_observed: git::notebook_status_porcelain(notebook_root).ok(),
722                preserved_paths: Some(vec![d.clone()]),
723                guidance: format!(
724                    "failed to restore baseline directory `{d}` after cleanup; do not retry blindly. underlying: {e}"
725                ),
726            });
727        }
728    }
729    // Explicitly delete transaction-owned outputs that reset/clean leave behind
730    // when they are Git-ignored untracked files.
731    let mut remaining = Vec::new();
732    for rel in remove_new_owned {
733        let abs = notebook_root.join(rel);
734        match std::fs::symlink_metadata(&abs) {
735            Ok(meta) if meta.file_type().is_symlink() || meta.is_file() => {
736                if let Err(e) = std::fs::remove_file(&abs) {
737                    remaining.push(format!("{rel} ({e})"));
738                }
739            }
740            Ok(meta) if meta.is_dir() => {
741                if let Err(e) = std::fs::remove_dir_all(&abs) {
742                    remaining.push(format!("{rel} ({e})"));
743                }
744            }
745            Ok(_) => {}
746            Err(e) if e.kind() == std::io::ErrorKind::NotFound => {}
747            Err(e) => remaining.push(format!("{rel} ({e})")),
748        }
749        // Prune only empty parents that the transaction created — never a
750        // directory that existed at baseline (e.g. pre-existing ignored parent).
751        if let Some(parent) = parent_path(rel) {
752            let mut cur = parent;
753            loop {
754                if baseline_dirs.contains(&cur) {
755                    break;
756                }
757                let p = notebook_root.join(&cur);
758                match std::fs::remove_dir(&p) {
759                    Ok(()) => {}
760                    Err(_) => break,
761                }
762                match parent_path(&cur) {
763                    Some(next) => cur = next,
764                    None => break,
765                }
766            }
767        }
768    }
769    if !remaining.is_empty() {
770        return Err(NbError::RecoveryRequired {
771            pre_revision: pre_revision.to_string(),
772            post_revision_observed: git::notebook_head(notebook_root).ok(),
773            status_observed: git::notebook_status_porcelain(notebook_root).ok(),
774            preserved_paths: Some(remaining),
775            guidance: "failed to remove transaction-owned outputs after aborted commit; do not retry blindly".into(),
776        });
777    }
778    // Verify none of the new owned paths remain (including ignored).
779    let mut still_present = Vec::new();
780    for rel in remove_new_owned {
781        if notebook_root.join(rel).exists() {
782            still_present.push(rel.clone());
783        }
784    }
785    let head = match restore_verify_head(notebook_root) {
786        Ok(h) => h,
787        Err(e) => {
788            return Err(NbError::RecoveryRequired {
789                pre_revision: pre_revision.to_string(),
790                post_revision_observed: None,
791                status_observed: git::notebook_status_porcelain(notebook_root).ok(),
792                preserved_paths: if still_present.is_empty() {
793                    None
794                } else {
795                    Some(still_present)
796                },
797                guidance: format!(
798                    "cleanup ran but HEAD re-read failed during verification; do not retry blindly. underlying: {e}"
799                ),
800            });
801        }
802    };
803    let dirty = match restore_verify_dirty(notebook_root) {
804        Ok(d) => d,
805        Err(e) => {
806            return Err(NbError::RecoveryRequired {
807                pre_revision: pre_revision.to_string(),
808                post_revision_observed: Some(head),
809                status_observed: git::notebook_status_porcelain(notebook_root).ok(),
810                preserved_paths: if still_present.is_empty() {
811                    None
812                } else {
813                    Some(still_present)
814                },
815                guidance: format!(
816                    "cleanup ran but dirty-status check failed during verification; do not retry blindly. underlying: {e}"
817                ),
818            });
819        }
820    };
821    if head != pre_revision || dirty || !still_present.is_empty() {
822        return Err(NbError::RecoveryRequired {
823            pre_revision: pre_revision.to_string(),
824            post_revision_observed: Some(head),
825            status_observed: git::notebook_status_porcelain(notebook_root).ok(),
826            preserved_paths: if still_present.is_empty() {
827                None
828            } else {
829                Some(still_present)
830            },
831            guidance:
832                "cleanup ran but HEAD/status/owned-path verification failed; do not retry blindly"
833                    .into(),
834        });
835    }
836    Ok(())
837}
838
839/// HEAD observation used only in post-cleanup verification.
840fn restore_verify_head(notebook_root: &Path) -> Result<String, NbError> {
841    #[cfg(feature = "testing")]
842    if std::env::var_os("NB_API_FAIL_RESTORE_HEAD").is_some() {
843        return Err(NbError::CommandFailed {
844            command: "nb-api://fail-restore-head".into(),
845            stderr: "injected HEAD verify failure for rollback tests".into(),
846            exit_code: Some(1),
847        });
848    }
849    git::notebook_head(notebook_root)
850}
851
852/// Dirty-status observation used only in post-cleanup verification.
853fn restore_verify_dirty(notebook_root: &Path) -> Result<bool, NbError> {
854    #[cfg(feature = "testing")]
855    if std::env::var_os("NB_API_FAIL_RESTORE_DIRTY").is_some() {
856        return Err(NbError::CommandFailed {
857            command: "nb-api://fail-restore-dirty".into(),
858            stderr: "injected dirty-status verify failure for rollback tests".into(),
859            exit_code: Some(1),
860        });
861    }
862    git::notebook_is_dirty(notebook_root)
863}
864
865/// Deterministic stand-in for an external `nb add` racing our snapshot
866/// (testing only, behind `NB_API_SIMULATE_EXTERNAL_WRITER`): create AND
867/// commit a note plus its `.index` line that this transaction knows nothing
868/// about. The commit must preserve both.
869///
870/// `NB_API_SIMULATE_EXTERNAL_SAME_PATH=<rel>` makes the external writer take
871/// the given path instead (to test the same-path race: our commit must fail
872/// `PathCollision`, never overwrite).
873#[cfg(feature = "testing")]
874fn simulate_external_writer(notebook_root: &Path) -> Result<(), NbError> {
875    use std::io::Write as _;
876    let (folder, name) = match std::env::var("NB_API_SIMULATE_EXTERNAL_SAME_PATH") {
877        Ok(rel) => {
878            let (folder, basename) = split_folder_basename(&normalize_rel(&rel));
879            (folder, basename)
880        }
881        Err(_) => (String::new(), format!("external-{}.md", std::process::id())),
882    };
883    let rel = if folder.is_empty() {
884        name.clone()
885    } else {
886        format!("{folder}/{name}")
887    };
888    if !folder.is_empty() {
889        std::fs::create_dir_all(notebook_root.join(&folder)).map_err(|e| NbError::Io {
890            path: notebook_root.join(&folder),
891            source: e.into(),
892        })?;
893    }
894    std::fs::write(notebook_root.join(&rel), b"# External\n\nexternal body\n").map_err(|e| {
895        NbError::Io {
896            path: notebook_root.join(&rel),
897            source: e.into(),
898        }
899    })?;
900    let index_abs = notebook_root.join(index_rel_for_folder(&folder));
901    let mut f = OpenOptions::new()
902        .create(true)
903        .append(true)
904        .open(&index_abs)
905        .map_err(|e| NbError::Io {
906            path: index_abs.clone(),
907            source: e.into(),
908        })?;
909    writeln!(f, "{name}").map_err(|e| NbError::Io {
910        path: index_abs.clone(),
911        source: e.into(),
912    })?;
913    drop(f);
914    git::notebook_commit_all(
915        notebook_root,
916        "external writer",
917        &[rel, index_rel_for_folder(&folder)],
918    )?;
919    Ok(())
920}
921
922/// Write the plan's effects to disk.
923///
924/// ONLY paths recorded in `effects` are touched: files created after the
925/// snapshot by an external writer are never deleted, and files deleted
926/// externally are never resurrected. `.index` rels are skipped here (applied
927/// separately from fresh on-disk content under `.nb-api-index.lock`).
928///
929/// `snapshot_keys` are the tree keys at snapshot time. A `created` path that
930/// exists on disk now but was absent from the snapshot means an external
931/// writer created the same path after our collision validation — refuse with
932/// `PathCollision` instead of overwriting it (which would also leave
933/// ambiguous duplicate `.index` entries).
934fn materialize_tree(
935    root: &Path,
936    tree: &VirtualTree,
937    effects: &PlanEffects,
938    snapshot_keys: &HashSet<String>,
939) -> Result<(), NbError> {
940    // Preflight: no path may traverse an existing symlink ancestor (including
941    // ignored directory symlinks excluded from the virtual snapshot).
942    for rel in tree.nodes.keys() {
943        refuse_symlink_ancestors(root, rel)?;
944    }
945
946    // Remove ONLY plan delete/move sources that exist on disk as files.
947    let mut removed: Vec<&String> = effects.removed.iter().collect();
948    removed.sort();
949    removed.dedup();
950    for rel in removed {
951        let key = normalize_rel(rel);
952        let abs = root.join(&key);
953        let meta = match std::fs::symlink_metadata(&abs) {
954            Ok(m) => m,
955            Err(e) if e.kind() == std::io::ErrorKind::NotFound => continue,
956            Err(e) => {
957                return Err(NbError::Io {
958                    path: abs,
959                    source: e.into(),
960                });
961            }
962        };
963        if meta.file_type().is_symlink() {
964            return Err(NbError::UnsupportedStructure {
965                reason: format!("refusing to materialize through symlink `{key}`"),
966            });
967        }
968        if meta.is_file() && !matches!(tree.nodes.get(&key), Some(VirtualNode::File(_))) {
969            std::fs::remove_file(&abs).map_err(|e| NbError::Io {
970                path: abs,
971                source: e.into(),
972            })?;
973        }
974    }
975    // Create ONLY plan folders.
976    let mut mkdirs: Vec<&String> = effects.mkdirs.iter().collect();
977    mkdirs.sort();
978    mkdirs.dedup();
979    for rel in mkdirs {
980        let key = normalize_rel(rel);
981        let abs = root.join(&key);
982        refuse_symlink_ancestors(root, &key)?;
983        std::fs::create_dir_all(&abs).map_err(|e| NbError::Io {
984            path: abs.clone(),
985            source: e.into(),
986        })?;
987    }
988    // Write ONLY plan-created/modified files (never `.index`).
989    let mut written: Vec<&String> = effects
990        .written
991        .iter()
992        .filter(|rel| !is_index_rel(rel))
993        .collect();
994    written.sort();
995    written.dedup();
996    let created: HashSet<&String> = effects.created.iter().collect();
997    for rel in written {
998        let key = normalize_rel(rel);
999        let created_contains = created.contains(rel);
1000        let Some(VirtualNode::File(bytes)) = tree.nodes.get(&key) else {
1001            return Err(NbError::ValidationError {
1002                reason: format!("plan effect `{key}` has no file content"),
1003                location: None,
1004            });
1005        };
1006        let abs = root.join(&key);
1007        // Never write through an existing symlink leaf or ancestor.
1008        refuse_symlink_ancestors(root, &key)?;
1009        if let Ok(meta) = std::fs::symlink_metadata(&abs) {
1010            if meta.file_type().is_symlink() {
1011                return Err(NbError::UnsupportedStructure {
1012                    reason: format!("refusing to write through symlink `{key}`"),
1013                });
1014            }
1015            // A planned create racing an external same-path create (file or
1016            // directory appearing after the snapshot): refuse instead of
1017            // overwriting the external note or failing obscurely on a dir.
1018            if created_contains && !snapshot_keys.contains(&key) {
1019                return Err(NbError::PathCollision {
1020                    path: key,
1021                    plan_index: None,
1022                });
1023            }
1024        }
1025        if let Some(parent) = abs.parent() {
1026            std::fs::create_dir_all(parent).map_err(|e| NbError::Io {
1027                path: parent.to_path_buf(),
1028                source: e.into(),
1029            })?;
1030        }
1031        std::fs::write(&abs, bytes).map_err(|e| NbError::Io {
1032            path: abs,
1033            source: e.into(),
1034        })?;
1035    }
1036    Ok(())
1037}
1038
1039/// Reject `rel` when any existing path component under `root` is a symlink.
1040///
1041/// Uses no-follow metadata so ignored directory symlinks (absent from the
1042/// virtual snapshot) cannot redirect `create_dir_all` / `write` outside the
1043/// notebook root.
1044fn refuse_symlink_ancestors(root: &Path, rel: &str) -> Result<(), NbError> {
1045    let mut acc = PathBuf::new();
1046    for part in rel.split('/').filter(|p| !p.is_empty()) {
1047        acc.push(part);
1048        let abs = root.join(&acc);
1049        match std::fs::symlink_metadata(&abs) {
1050            Ok(meta) if meta.file_type().is_symlink() => {
1051                let key = acc.to_string_lossy().replace('\\', "/");
1052                return Err(NbError::UnsupportedStructure {
1053                    reason: format!(
1054                        "refusing path through symlink `{key}`; transactions do not follow symlinks"
1055                    ),
1056                });
1057            }
1058            Ok(_) => {}
1059            Err(e) if e.kind() == std::io::ErrorKind::NotFound => break,
1060            Err(e) => {
1061                return Err(NbError::Io {
1062                    path: abs,
1063                    source: e.into(),
1064                });
1065            }
1066        }
1067    }
1068    Ok(())
1069}
1070
1071fn outcome_selector(notebook: &str, target: &NoteTarget, resolved_path: &str) -> String {
1072    match target {
1073        NoteTarget::Selector { value } => {
1074            if value.contains(':') {
1075                value.clone()
1076            } else {
1077                format!("{notebook}:{value}")
1078            }
1079        }
1080        NoteTarget::Path { .. } => format!("{notebook}:{resolved_path}"),
1081    }
1082}
1083
1084struct OpMeta {
1085    path: Option<String>,
1086    selector: Option<String>,
1087    noop: bool,
1088    fingerprint: Option<Fingerprint>,
1089    index_edits: Vec<PendingIndexEdit>,
1090}
1091
1092/// Paths the plan dirties. Materialization touches ONLY these paths: files
1093/// created after the snapshot (e.g. an external `nb add` racing our commit)
1094/// are never deleted, and files deleted externally are never resurrected.
1095#[derive(Debug, Default)]
1096struct PlanEffects {
1097    /// Delete/move sources: the only paths materialize may remove.
1098    removed: Vec<String>,
1099    /// Created or modified file paths: the only files materialize writes
1100    /// (`.index` rels excluded — applied separately under the index lock).
1101    written: Vec<String>,
1102    /// Paths that must NOT exist on disk at materialize time (creates and
1103    /// move destinations): a file appearing after the snapshot means an
1104    /// external writer raced us — refuse with `PathCollision` instead of
1105    /// overwriting it.
1106    created: Vec<String>,
1107    /// Folders created by the plan.
1108    mkdirs: Vec<String>,
1109}
1110
1111/// One `.index` mutation derived from a validated plan op.
1112///
1113/// `file_rel` is the notebook-relative `.index` path (`.index` at root,
1114/// `<folder>/.index` otherwise). Applied to fresh on-disk content under the
1115/// `.nb-api-index.lock`, in plan order, after non-index files materialize.
1116#[derive(Debug, Clone)]
1117struct PendingIndexEdit {
1118    file_rel: String,
1119    kind: PendingIndexKind,
1120}
1121
1122#[derive(Debug, Clone)]
1123enum PendingIndexKind {
1124    Append {
1125        basename: String,
1126    },
1127    Blank {
1128        basename: String,
1129    },
1130    Rename {
1131        old_basename: String,
1132        new_basename: String,
1133    },
1134}
1135
1136fn validate_and_apply_virtual(
1137    notebook: &str,
1138    notebook_root: &Path,
1139    tree: &mut VirtualTree,
1140    ignored_existing: &HashSet<String>,
1141    op: &PlanOp,
1142    _index: usize,
1143    effects: &mut PlanEffects,
1144) -> Result<OpMeta, NbError> {
1145    match op {
1146        PlanOp::AddNote {
1147            path,
1148            title,
1149            content,
1150            tags,
1151        } => {
1152            refuse_create_collision(notebook_root, tree, ignored_existing, path)?;
1153            let bytes = build_note_bytes(title.as_deref(), content, tags);
1154            let fp = fingerprint_bytes(&bytes, path)?;
1155            tree.insert_file(path.clone(), bytes);
1156            effects.written.push(path.clone());
1157            effects.created.push(path.clone());
1158            Ok(OpMeta {
1159                path: Some(path.clone()),
1160                selector: Some(format!("{notebook}:{path}")),
1161                noop: false,
1162                fingerprint: Some(fp),
1163                index_edits: vec![append_index_edit(path)],
1164            })
1165        }
1166        PlanOp::AddTodo {
1167            path,
1168            title,
1169            description,
1170            tasks,
1171            tags,
1172        } => {
1173            refuse_create_collision(notebook_root, tree, ignored_existing, path)?;
1174            let bytes = build_todo_bytes(title, description.as_deref(), tasks, tags);
1175            let fp = fingerprint_bytes(&bytes, path)?;
1176            tree.insert_file(path.clone(), bytes);
1177            effects.written.push(path.clone());
1178            effects.created.push(path.clone());
1179            Ok(OpMeta {
1180                path: Some(path.clone()),
1181                selector: Some(format!("{notebook}:{path}")),
1182                noop: false,
1183                fingerprint: Some(fp),
1184                index_edits: vec![append_index_edit(path)],
1185            })
1186        }
1187        PlanOp::AddBookmark {
1188            path,
1189            url,
1190            title,
1191            tags,
1192            comment,
1193        } => {
1194            refuse_create_collision(notebook_root, tree, ignored_existing, path)?;
1195            let bytes = build_bookmark_bytes(url, title.as_deref(), tags, comment.as_deref());
1196            let fp = fingerprint_bytes(&bytes, path)?;
1197            tree.insert_file(path.clone(), bytes);
1198            effects.written.push(path.clone());
1199            effects.created.push(path.clone());
1200            Ok(OpMeta {
1201                path: Some(path.clone()),
1202                selector: Some(format!("{notebook}:{path}")),
1203                noop: false,
1204                fingerprint: Some(fp),
1205                index_edits: vec![append_index_edit(path)],
1206            })
1207        }
1208        PlanOp::AddFolder { path } => {
1209            refuse_create_collision(notebook_root, tree, ignored_existing, path)?;
1210            let keep = format!("{path}/.gitkeep");
1211            refuse_create_collision(notebook_root, tree, ignored_existing, &keep)?;
1212            tree.insert_folder(path.clone());
1213            effects.mkdirs.push(path.clone());
1214            // Git cannot track empty dirs; persist a keep file so the folder
1215            // survives commit/checkout/clone. Force-staged at checkpoint.
1216            if !tree.exists(&keep) {
1217                tree.insert_file(keep.clone(), Vec::new());
1218            }
1219            effects.written.push(keep.clone());
1220            effects.created.push(keep);
1221            Ok(OpMeta {
1222                path: Some(path.clone()),
1223                selector: None,
1224                noop: false,
1225                fingerprint: None,
1226                index_edits: Vec::new(),
1227            })
1228        }
1229        PlanOp::DeleteNote { target } => {
1230            let path = resolve_target_path(tree, ignored_existing, target)?;
1231            if !tree.exists(&path) {
1232                return Err(NbError::NotFound {
1233                    selector: target.value().to_string(),
1234                });
1235            }
1236            tree.remove(&path);
1237            effects.removed.push(path.clone());
1238            Ok(OpMeta {
1239                path: Some(path.clone()),
1240                selector: Some(outcome_selector(notebook, target, &path)),
1241                noop: false,
1242                fingerprint: None,
1243                index_edits: vec![blank_index_edit(&path)],
1244            })
1245        }
1246        PlanOp::MoveNote {
1247            target,
1248            destination,
1249        } => {
1250            let from = resolve_target_path(tree, ignored_existing, target)?;
1251            let to = resolve_move_destination(&from, destination);
1252            refuse_create_collision(notebook_root, tree, ignored_existing, &to)?;
1253            // Same-folder renames update the `.index` line in place, which
1254            // is only lossless when the new name is not longer than the old
1255            // one (the splice prefix must not overlap the appender region).
1256            // A longer in-folder rename is refused: delete + recreate the
1257            // note (new id) instead. Cross-folder moves are blank + append
1258            // and are always safe.
1259            let (from_folder, from_base) = split_folder_basename(&from);
1260            let (to_folder, to_base) = split_folder_basename(&to);
1261            if from_folder == to_folder && to_base.len() > from_base.len() {
1262                return Err(NbError::ValidationError {
1263                    reason: format!(
1264                        "in-folder rename to a longer name (`{from_base}` -> `{to_base}`) would risk concurrent .index appends; delete and recreate the note instead"
1265                    ),
1266                    location: None,
1267                });
1268            }
1269            tree.rename(&from, &to)?;
1270            effects.removed.push(from.clone());
1271            effects.written.push(to.clone());
1272            effects.created.push(to.clone());
1273            Ok(OpMeta {
1274                path: Some(to.clone()),
1275                selector: Some(format!("{notebook}:{to}")),
1276                noop: false,
1277                fingerprint: None,
1278                index_edits: move_index_edits(&from, &to),
1279            })
1280        }
1281        PlanOp::MarkTaskDone {
1282            target,
1283            task_number,
1284        } => {
1285            let path = resolve_target_path(tree, ignored_existing, target)?;
1286            let bytes = tree
1287                .get_file(&path)
1288                .ok_or_else(|| NbError::NotFound {
1289                    selector: target.value().to_string(),
1290                })?
1291                .to_vec();
1292            let new_bytes = set_todo_state(&bytes, &path, true, *task_number)?;
1293            let noop = new_bytes == bytes;
1294            let fp = fingerprint_bytes(&new_bytes, &path)?;
1295            tree.insert_file(path.clone(), new_bytes);
1296            effects.written.push(path.clone());
1297            Ok(OpMeta {
1298                path: Some(path.clone()),
1299                selector: Some(outcome_selector(notebook, target, &path)),
1300                noop,
1301                fingerprint: Some(fp),
1302                index_edits: Vec::new(),
1303            })
1304        }
1305        PlanOp::UnmarkTaskDone {
1306            target,
1307            task_number,
1308        } => {
1309            let path = resolve_target_path(tree, ignored_existing, target)?;
1310            let bytes = tree
1311                .get_file(&path)
1312                .ok_or_else(|| NbError::NotFound {
1313                    selector: target.value().to_string(),
1314                })?
1315                .to_vec();
1316            let new_bytes = set_todo_state(&bytes, &path, false, *task_number)?;
1317            let noop = new_bytes == bytes;
1318            let fp = fingerprint_bytes(&new_bytes, &path)?;
1319            tree.insert_file(path.clone(), new_bytes);
1320            effects.written.push(path.clone());
1321            Ok(OpMeta {
1322                path: Some(path.clone()),
1323                selector: Some(outcome_selector(notebook, target, &path)),
1324                noop,
1325                fingerprint: Some(fp),
1326                index_edits: Vec::new(),
1327            })
1328        }
1329        PlanOp::ReplaceNoteBody {
1330            target,
1331            new_body,
1332            fingerprint: expected,
1333        } => {
1334            let path = resolve_target_path(tree, ignored_existing, target)?;
1335            let bytes = tree
1336                .get_file(&path)
1337                .ok_or_else(|| NbError::NotFound {
1338                    selector: target.value().to_string(),
1339                })?
1340                .to_vec();
1341            let doc = parse_doc(&bytes, &path)?;
1342            // Contiguity before fingerprint so fragmented bodies always surface
1343            // FragmentedBody even with a stale fingerprint.
1344            require_contiguous_body(&doc)?;
1345            let current = fingerprint::fingerprint(&doc);
1346            if &current != expected {
1347                return Err(NbError::FingerprintMismatch {
1348                    target: target.clone(),
1349                    guidance: "body fingerprint does not match; re-read and retry".into(),
1350                });
1351            }
1352            let new_bytes = splice_body(&doc, new_body.as_bytes())?;
1353            let fp = fingerprint_bytes(&new_bytes, &path)?;
1354            let noop = new_bytes == bytes;
1355            tree.insert_file(path.clone(), new_bytes);
1356            effects.written.push(path.clone());
1357            Ok(OpMeta {
1358                path: Some(path.clone()),
1359                selector: Some(outcome_selector(notebook, target, &path)),
1360                noop,
1361                fingerprint: Some(fp),
1362                index_edits: Vec::new(),
1363            })
1364        }
1365        PlanOp::EditNoteSubstring {
1366            target,
1367            pattern,
1368            replacement,
1369            occurrence,
1370            expected_count,
1371            fingerprint: expected,
1372        } => {
1373            let path = resolve_target_path(tree, ignored_existing, target)?;
1374            let bytes = tree
1375                .get_file(&path)
1376                .ok_or_else(|| NbError::NotFound {
1377                    selector: target.value().to_string(),
1378                })?
1379                .to_vec();
1380            let doc = parse_doc(&bytes, &path)?;
1381            let body = require_contiguous_body(&doc)?;
1382            if let Some(exp) = expected {
1383                let current = fingerprint::fingerprint(&doc);
1384                if &current != exp {
1385                    return Err(NbError::FingerprintMismatch {
1386                        target: target.clone(),
1387                        guidance: "body fingerprint does not match; re-read and retry".into(),
1388                    });
1389                }
1390            }
1391            let new_body = apply_substring(
1392                &body,
1393                pattern.as_bytes(),
1394                replacement.as_bytes(),
1395                occurrence,
1396                *expected_count,
1397            )?;
1398            let new_bytes = splice_body(&doc, &new_body)?;
1399            let fp = fingerprint_bytes(&new_bytes, &path)?;
1400            let noop = new_bytes == bytes;
1401            tree.insert_file(path.clone(), new_bytes);
1402            effects.written.push(path.clone());
1403            Ok(OpMeta {
1404                path: Some(path.clone()),
1405                selector: Some(outcome_selector(notebook, target, &path)),
1406                noop,
1407                fingerprint: Some(fp),
1408                index_edits: Vec::new(),
1409            })
1410        }
1411        PlanOp::EditNoteLines { target, edits } => {
1412            let path = resolve_target_path(tree, ignored_existing, target)?;
1413            let bytes = tree
1414                .get_file(&path)
1415                .ok_or_else(|| NbError::NotFound {
1416                    selector: target.value().to_string(),
1417                })?
1418                .to_vec();
1419            let doc = parse_doc(&bytes, &path)?;
1420            let body = require_contiguous_body(&doc)?;
1421            let new_body = apply_line_edits(&body, edits)?;
1422            let new_bytes = splice_body(&doc, &new_body)?;
1423            let fp = fingerprint_bytes(&new_bytes, &path)?;
1424            let noop = new_bytes == bytes;
1425            tree.insert_file(path.clone(), new_bytes);
1426            effects.written.push(path.clone());
1427            Ok(OpMeta {
1428                path: Some(path.clone()),
1429                selector: Some(outcome_selector(notebook, target, &path)),
1430                noop,
1431                fingerprint: Some(fp),
1432                index_edits: Vec::new(),
1433            })
1434        }
1435        PlanOp::RetitleNote { target, title } => {
1436            let path = resolve_target_path(tree, ignored_existing, target)?;
1437            let bytes = tree
1438                .get_file(&path)
1439                .ok_or_else(|| NbError::NotFound {
1440                    selector: target.value().to_string(),
1441                })?
1442                .to_vec();
1443            let doc = parse_doc(&bytes, &path)?;
1444            let mut title_line = title.clone();
1445            if !title_line.starts_with('#') {
1446                title_line = format!("# {title_line}");
1447            }
1448            let new_bytes = splice_title(&doc, title_line.as_bytes())?;
1449            let fp = fingerprint_bytes(&new_bytes, &path)?;
1450            let noop = new_bytes == bytes;
1451            tree.insert_file(path.clone(), new_bytes);
1452            effects.written.push(path.clone());
1453            Ok(OpMeta {
1454                path: Some(path.clone()),
1455                selector: Some(outcome_selector(notebook, target, &path)),
1456                noop,
1457                fingerprint: Some(fp),
1458                index_edits: Vec::new(),
1459            })
1460        }
1461        PlanOp::EditNoteTags {
1462            target,
1463            add,
1464            remove,
1465        } => {
1466            let path = resolve_target_path(tree, ignored_existing, target)?;
1467            let bytes = tree
1468                .get_file(&path)
1469                .ok_or_else(|| NbError::NotFound {
1470                    selector: target.value().to_string(),
1471                })?
1472                .to_vec();
1473            let doc = parse_doc(&bytes, &path)?;
1474            let new_bytes = apply_tag_edit(&doc, &path, add, remove)?;
1475            let fp = fingerprint_bytes(&new_bytes, &path)?;
1476            let noop = new_bytes == bytes;
1477            tree.insert_file(path.clone(), new_bytes);
1478            effects.written.push(path.clone());
1479            Ok(OpMeta {
1480                path: Some(path.clone()),
1481                selector: Some(outcome_selector(notebook, target, &path)),
1482                noop,
1483                fingerprint: Some(fp),
1484                index_edits: Vec::new(),
1485            })
1486        }
1487    }
1488}
1489
1490fn refuse_create_collision(
1491    notebook_root: &Path,
1492    tree: &VirtualTree,
1493    ignored_existing: &HashSet<String>,
1494    path: &str,
1495) -> Result<(), NbError> {
1496    if ignored_existing.contains(path) {
1497        return Err(NbError::PathIgnored {
1498            path: path.to_string(),
1499            guidance: "path exists as a Git-ignored file; un-ignore or remove it outside the transaction before creating here".into(),
1500            plan_index: None,
1501        });
1502    }
1503    // Ignored directory/file symlinks are absent from the virtual tree; reject
1504    // creates whose prefix is an ignored symlink (or any on-disk symlink).
1505    refuse_symlink_ancestors(notebook_root, path)?;
1506    for ig in ignored_existing {
1507        if path == ig || path.starts_with(&format!("{ig}/")) {
1508            let abs = notebook_root.join(ig);
1509            if let Ok(meta) = std::fs::symlink_metadata(&abs)
1510                && meta.file_type().is_symlink()
1511            {
1512                return Err(NbError::UnsupportedStructure {
1513                    reason: format!(
1514                        "refusing path through symlink `{ig}`; transactions do not follow symlinks"
1515                    ),
1516                });
1517            }
1518        }
1519    }
1520    if tree.exists(path) {
1521        return Err(NbError::PathCollision {
1522            path: path.to_string(),
1523            plan_index: None,
1524        });
1525    }
1526    Ok(())
1527}
1528
1529fn refuse_existing_ignored(ignored_existing: &HashSet<String>, path: &str) -> Result<(), NbError> {
1530    if ignored_existing.contains(path) {
1531        return Err(NbError::PathIgnored {
1532            path: path.to_string(),
1533            guidance:
1534                "cannot edit, delete, or move an existing Git-ignored path inside a transaction"
1535                    .into(),
1536            plan_index: None,
1537        });
1538    }
1539    Ok(())
1540}
1541
1542fn resolve_target_path(
1543    tree: &VirtualTree,
1544    ignored_existing: &HashSet<String>,
1545    target: &NoteTarget,
1546) -> Result<String, NbError> {
1547    match target {
1548        NoteTarget::Path { value } => {
1549            let path = normalize_rel(value);
1550            refuse_existing_ignored(ignored_existing, &path)?;
1551            if tree.exists(&path) {
1552                return Ok(path);
1553            }
1554            // Allow selector-like numeric ids only via Selector variant.
1555            Err(NbError::NotFound {
1556                selector: value.clone(),
1557            })
1558        }
1559        NoteTarget::Selector { value } => {
1560            // Prefer exact path match when value looks like a path.
1561            let stripped = value
1562                .rsplit_once(':')
1563                .map(|(_, rest)| rest)
1564                .unwrap_or(value.as_str());
1565            let candidate = normalize_rel(stripped);
1566            refuse_existing_ignored(ignored_existing, &candidate)?;
1567            if tree.exists(&candidate) {
1568                return Ok(candidate);
1569            }
1570            // Numeric `<folder>/<id>` / `<id>` via the virtual `.index`
1571            // (blank lines are dead ids -> NotFound, never reused).
1572            if let Some(resolved) = resolve_numeric_in_tree(tree, &candidate) {
1573                return resolved;
1574            }
1575            // Match by basename or unique suffix.
1576            let matches: Vec<_> = tree
1577                .nodes
1578                .iter()
1579                .filter_map(|(p, n)| match n {
1580                    VirtualNode::File(_)
1581                        if p == &candidate
1582                            || p.ends_with(&format!("/{candidate}"))
1583                            || Path::new(p).file_stem().and_then(|s| s.to_str())
1584                                == Some(stripped)
1585                            || p.ends_with(stripped) =>
1586                    {
1587                        Some(p.clone())
1588                    }
1589                    _ => None,
1590                })
1591                .collect();
1592            match matches.as_slice() {
1593                [one] => Ok(one.clone()),
1594                [] => {
1595                    // Existing ignored paths are not in the editable tree.
1596                    if ignored_existing.contains(&candidate) {
1597                        return Err(NbError::PathIgnored {
1598                            path: candidate,
1599                            guidance: "cannot edit, delete, or move an existing Git-ignored path inside a transaction".into(),
1600                            plan_index: None,
1601                        });
1602                    }
1603                    for ig in ignored_existing {
1604                        if ig.ends_with(&format!("/{candidate}")) || ig.ends_with(stripped) {
1605                            return Err(NbError::PathIgnored {
1606                                path: ig.clone(),
1607                                guidance: "cannot edit, delete, or move an existing Git-ignored path inside a transaction".into(),
1608                                plan_index: None,
1609                            });
1610                        }
1611                    }
1612                    Err(NbError::NotFound {
1613                        selector: value.clone(),
1614                    })
1615                }
1616                _ => Err(NbError::ValidationError {
1617                    reason: format!("selector `{value}` is ambiguous across multiple paths"),
1618                    location: None,
1619                }),
1620            }
1621        }
1622    }
1623}
1624
1625/// Resolve `<folder>/<id>` or `<id>` against the virtual `.index`.
1626///
1627/// Returns `Some(Ok(path))` on a live entry, `Some(Err(NotFound))` when the
1628/// line exists but is blank (deleted id) or out of range, and `None` when
1629/// the value is not numeric-id shaped (caller falls through to name
1630/// matching).
1631fn resolve_numeric_in_tree(tree: &VirtualTree, candidate: &str) -> Option<Result<String, NbError>> {
1632    let (folder, id_str) = match candidate.rfind('/') {
1633        Some(i) => (candidate[..i].to_string(), candidate[i + 1..].to_string()),
1634        None => (String::new(), candidate.to_string()),
1635    };
1636    let id: usize = match id_str.parse() {
1637        Ok(n) => n,
1638        Err(_) => return None,
1639    };
1640    if id == 0 {
1641        return Some(Err(NbError::NotFound {
1642            selector: candidate.to_string(),
1643        }));
1644    }
1645    let rel = index_rel_for_folder(&folder);
1646    let bytes = match tree.nodes.get(&rel) {
1647        Some(VirtualNode::File(b)) => b.clone(),
1648        _ => return None,
1649    };
1650    let lines = parse_index_lines(&bytes);
1651    match lines.get(id - 1) {
1652        Some(name) if !name.trim().is_empty() => {
1653            let path = if folder.is_empty() {
1654                name.clone()
1655            } else {
1656                format!("{folder}/{name}")
1657            };
1658            Some(Ok(path))
1659        }
1660        _ => Some(Err(NbError::NotFound {
1661            selector: candidate.to_string(),
1662        })),
1663    }
1664}
1665
1666fn resolve_move_destination(from: &str, destination: &str) -> String {
1667    // A trailing slash means "into folder" (basename kept). Check the raw
1668    // form: `normalize_rel` trims slashes, so a post-normalize check would
1669    // be dead code.
1670    let into_folder = destination.trim_end().ends_with('/');
1671    let dest = normalize_rel(destination);
1672    if into_folder {
1673        let base = Path::new(from)
1674            .file_name()
1675            .and_then(|s| s.to_str())
1676            .unwrap_or(from);
1677        return normalize_rel(&format!("{dest}/{base}"));
1678    }
1679    // Destination is a folder path without slash if no extension and exists as folder —
1680    // treat as basename rename when it has a file extension or contains a dot filename.
1681    dest
1682}
1683
1684fn parse_doc(bytes: &[u8], path: &str) -> Result<NoteDocument, NbError> {
1685    parse(bytes, ParseContext::FromPath(PathBuf::from(path)))
1686}
1687
1688fn fingerprint_bytes(bytes: &[u8], path: &str) -> Result<Fingerprint, NbError> {
1689    let doc = parse_doc(bytes, path)?;
1690    Ok(fingerprint::fingerprint(&doc))
1691}
1692
1693fn build_note_bytes(title: Option<&str>, content: &str, tags: &[String]) -> Vec<u8> {
1694    let mut out = Vec::new();
1695    if let Some(t) = title {
1696        out.extend_from_slice(format!("# {t}\n\n").as_bytes());
1697    }
1698    if !tags.is_empty() {
1699        let mut first = true;
1700        for tag in tags {
1701            if !first {
1702                out.push(b' ');
1703            }
1704            first = false;
1705            if tag.starts_with('#') {
1706                out.extend_from_slice(tag.as_bytes());
1707            } else {
1708                out.push(b'#');
1709                out.extend_from_slice(tag.as_bytes());
1710            }
1711        }
1712        out.extend_from_slice(b"\n\n");
1713    }
1714    out.extend_from_slice(content.as_bytes());
1715    out
1716}
1717
1718fn build_todo_bytes(
1719    title: &str,
1720    description: Option<&str>,
1721    tasks: &[String],
1722    tags: &[String],
1723) -> Vec<u8> {
1724    let mut out = Vec::new();
1725    let title_line = if title.contains('[') {
1726        format!("# {title}\n\n")
1727    } else {
1728        format!("# [ ] {title}\n\n")
1729    };
1730    out.extend_from_slice(title_line.as_bytes());
1731    if !tasks.is_empty() {
1732        out.extend_from_slice(b"## Tasks\n\n");
1733        for task in tasks {
1734            out.extend_from_slice(format!("- [ ] {task}\n").as_bytes());
1735        }
1736        out.push(b'\n');
1737    }
1738    if let Some(desc) = description {
1739        out.extend_from_slice(b"## Description\n\n");
1740        out.extend_from_slice(desc.as_bytes());
1741        if !desc.ends_with('\n') {
1742            out.push(b'\n');
1743        }
1744        out.push(b'\n');
1745    }
1746    if !tags.is_empty() {
1747        out.extend_from_slice(b"## Tags\n\n");
1748        let mut first = true;
1749        for tag in tags {
1750            if !first {
1751                out.push(b' ');
1752            }
1753            first = false;
1754            if tag.starts_with('#') {
1755                out.extend_from_slice(tag.as_bytes());
1756            } else {
1757                out.push(b'#');
1758                out.extend_from_slice(tag.as_bytes());
1759            }
1760        }
1761        out.push(b'\n');
1762    }
1763    out
1764}
1765
1766fn build_bookmark_bytes(
1767    url: &str,
1768    title: Option<&str>,
1769    tags: &[String],
1770    comment: Option<&str>,
1771) -> Vec<u8> {
1772    let mut out = Vec::new();
1773    if let Some(t) = title {
1774        out.extend_from_slice(format!("# {t}\n\n").as_bytes());
1775    }
1776    out.extend_from_slice(format!("<{url}>\n\n").as_bytes());
1777    if let Some(c) = comment {
1778        out.extend_from_slice(b"## Content\n\n");
1779        out.extend_from_slice(c.as_bytes());
1780        if !c.ends_with('\n') {
1781            out.push(b'\n');
1782        }
1783        out.push(b'\n');
1784    }
1785    if !tags.is_empty() {
1786        out.extend_from_slice(b"## Tags\n\n");
1787        let mut first = true;
1788        for tag in tags {
1789            if !first {
1790                out.push(b' ');
1791            }
1792            first = false;
1793            if tag.starts_with('#') {
1794                out.extend_from_slice(tag.as_bytes());
1795            } else {
1796                out.push(b'#');
1797                out.extend_from_slice(tag.as_bytes());
1798            }
1799        }
1800        out.push(b'\n');
1801    }
1802    out
1803}
1804
1805fn set_todo_state(
1806    bytes: &[u8],
1807    path: &str,
1808    done: bool,
1809    task_number: Option<u32>,
1810) -> Result<Vec<u8>, NbError> {
1811    let doc = parse_doc(bytes, path)?;
1812    if doc.kind() != DocumentKind::Todo {
1813        return Err(NbError::UnsupportedStructure {
1814            reason: "mark_task_done/unmark_task_done require a Todo document".into(),
1815        });
1816    }
1817    let mut out = bytes.to_vec();
1818    if let Some(n) = task_number {
1819        // Flip Nth `- [ ]` / `- [x]` checklist item (1-based).
1820        let mut count = 0u32;
1821        let mut i = 0usize;
1822        while i + 5 < out.len() {
1823            if out[i] == b'-' && out[i + 1] == b' ' && out[i + 2] == b'[' {
1824                let close = out[i + 4];
1825                if close == b']' {
1826                    count += 1;
1827                    if count == n {
1828                        let mark = if done { b'x' } else { b' ' };
1829                        out[i + 3] = mark;
1830                        return Ok(out);
1831                    }
1832                }
1833            }
1834            i += 1;
1835        }
1836        return Err(NbError::ValidationError {
1837            reason: format!("task_number {n} not found"),
1838            location: None,
1839        });
1840    }
1841    // Title checkbox.
1842    if let Some(range) = doc.title_byte_range() {
1843        let title = &out[range.clone()];
1844        let replaced = if done {
1845            replace_checkbox(title, true)
1846        } else {
1847            replace_checkbox(title, false)
1848        };
1849        out.splice(range, replaced);
1850    }
1851    Ok(out)
1852}
1853
1854fn replace_checkbox(title: &[u8], done: bool) -> Vec<u8> {
1855    let s = String::from_utf8_lossy(title);
1856    let mark = if done { "[x]" } else { "[ ]" };
1857    let new = if s.contains("[x]") || s.contains("[X]") {
1858        s.replacen("[x]", mark, 1).replacen("[X]", mark, 1)
1859    } else if s.contains("[ ]") {
1860        s.replacen("[ ]", mark, 1)
1861    } else {
1862        // Insert after `# `
1863        if let Some(rest) = s.strip_prefix("# ") {
1864            format!("# {mark} {rest}")
1865        } else {
1866            s.into_owned()
1867        }
1868    };
1869    new.into_bytes()
1870}
1871
1872fn apply_tag_edit(
1873    doc: &NoteDocument,
1874    path: &str,
1875    add: &[String],
1876    remove: &[String],
1877) -> Result<Vec<u8>, NbError> {
1878    let mut tags: Vec<String> = doc
1879        .tags_str()
1880        .filter_map(|t| t.ok().map(|s| s.trim_start_matches('#').to_string()))
1881        .collect();
1882    for r in remove {
1883        let key = r.trim_start_matches('#');
1884        tags.retain(|t| t != key);
1885    }
1886    for a in add {
1887        let key = a.trim_start_matches('#').to_string();
1888        if !tags.iter().any(|t| t == &key) {
1889            tags.push(key);
1890        }
1891    }
1892    let source = doc.source();
1893    let result = match doc.kind() {
1894        DocumentKind::Note => {
1895            let tag_line = if tags.is_empty() {
1896                None
1897            } else {
1898                Some(
1899                    tags.iter()
1900                        .map(|t| format!("#{t}"))
1901                        .collect::<Vec<_>>()
1902                        .join(" ")
1903                        + "\n",
1904                )
1905            };
1906            if let Some(range) = doc.tags_byte_range() {
1907                let mut out = source.to_vec();
1908                match tag_line {
1909                    Some(line) => {
1910                        out.splice(range, line.into_bytes());
1911                    }
1912                    None => {
1913                        out.splice(range, std::iter::empty::<u8>());
1914                    }
1915                }
1916                Ok(out)
1917            } else if let Some(line) = tag_line {
1918                // Insert after title or at start.
1919                let insert_at = doc.title_byte_range().map(|r| r.end).unwrap_or(0);
1920                let mut block = Vec::new();
1921                if insert_at > 0 {
1922                    block.push(b'\n');
1923                }
1924                block.extend_from_slice(line.as_bytes());
1925                block.push(b'\n');
1926                let mut out = source.to_vec();
1927                out.splice(insert_at..insert_at, block);
1928                Ok(out)
1929            } else {
1930                Ok(source.to_vec())
1931            }
1932        }
1933        DocumentKind::Todo | DocumentKind::Bookmark => {
1934            let section = if tags.is_empty() {
1935                None
1936            } else {
1937                Some(format!(
1938                    "## Tags\n\n{}\n",
1939                    tags.iter()
1940                        .map(|t| format!("#{t}"))
1941                        .collect::<Vec<_>>()
1942                        .join(" ")
1943                ))
1944            };
1945            if let Some(range) = doc.tags_byte_range() {
1946                let mut out = source.to_vec();
1947                let replacement = section.map(|s| s.into_bytes()).unwrap_or_default();
1948                out.splice(range, replacement);
1949                Ok(out)
1950            } else if let Some(s) = section {
1951                let mut out = source.to_vec();
1952                if !out.ends_with(b"\n") {
1953                    out.push(b'\n');
1954                }
1955                out.push(b'\n');
1956                out.extend_from_slice(s.as_bytes());
1957                Ok(out)
1958            } else {
1959                Ok(source.to_vec())
1960            }
1961        }
1962    };
1963    let _ = path;
1964    result
1965}
1966
1967fn annotate_plan_index(err: NbError, index: u32) -> NbError {
1968    match err {
1969        NbError::PathCollision { path, .. } => NbError::PathCollision {
1970            path,
1971            plan_index: Some(index),
1972        },
1973        NbError::PathIgnored { path, guidance, .. } => NbError::PathIgnored {
1974            path,
1975            guidance,
1976            plan_index: Some(index),
1977        },
1978        NbError::FingerprintMismatch { .. }
1979        | NbError::AnchorMismatch { .. }
1980        | NbError::OccurrenceMismatch { .. }
1981        | NbError::OverlappingEdits { .. }
1982        | NbError::FragmentedBody { .. }
1983        | NbError::EmptySubstringPattern
1984        | NbError::NotFound { .. }
1985        | NbError::UnsupportedStructure { .. } => err,
1986        NbError::PlanValidation {
1987            kind,
1988            message,
1989            plan_index: _,
1990        } => NbError::PlanValidation {
1991            kind,
1992            message,
1993            plan_index: Some(index),
1994        },
1995        other => NbError::PlanValidation {
1996            kind: "op_failed".into(),
1997            message: other.to_string(),
1998            plan_index: Some(index),
1999        },
2000    }
2001}
2002
2003fn validate_target(target: &NoteTarget) -> Result<(), NbError> {
2004    if target.value().trim().is_empty() {
2005        return Err(NbError::ValidationError {
2006            reason: "note target must not be empty".into(),
2007            location: None,
2008        });
2009    }
2010    Ok(())
2011}
2012
2013fn validate_create_path(path: &str, file: bool) -> Result<String, NbError> {
2014    // Validate the caller-supplied string before any normalization so
2015    // absolute and backslash forms cannot be silently rewritten.
2016    let raw = path.trim();
2017    if raw.is_empty() {
2018        return Err(NbError::ValidationError {
2019            reason: "path must not be empty".into(),
2020            location: None,
2021        });
2022    }
2023    if raw.starts_with('/') || raw.starts_with('\\') || Path::new(raw).is_absolute() {
2024        return Err(NbError::ValidationError {
2025            reason: "path must be notebook-relative (absolute paths refused)".into(),
2026            location: None,
2027        });
2028    }
2029    if raw.contains('\\') {
2030        return Err(NbError::ValidationError {
2031            reason: "path must not contain backslash separators".into(),
2032            location: None,
2033        });
2034    }
2035    if raw.contains('\0') {
2036        return Err(NbError::ValidationError {
2037            reason: "path must not contain NUL".into(),
2038            location: None,
2039        });
2040    }
2041    let path = normalize_rel(raw);
2042    if path.is_empty() {
2043        return Err(NbError::ValidationError {
2044            reason: "path must not be empty".into(),
2045            location: None,
2046        });
2047    }
2048    if path
2049        .split('/')
2050        .any(|p| p.is_empty() || p == "." || p == "..")
2051    {
2052        return Err(NbError::ValidationError {
2053            reason: "path must not contain empty, `.`, or `..` segments".into(),
2054            location: None,
2055        });
2056    }
2057    if file {
2058        let name = Path::new(&path)
2059            .file_name()
2060            .and_then(|s| s.to_str())
2061            .unwrap_or("");
2062        if name.is_empty() {
2063            return Err(NbError::ValidationError {
2064                reason: "create path must include a filename".into(),
2065                location: None,
2066            });
2067        }
2068    }
2069    Ok(path)
2070}
2071
2072fn normalize_rel(path: &str) -> String {
2073    path.trim()
2074        .trim_start_matches("./")
2075        .trim_matches('/')
2076        .replace('\\', "/")
2077}
2078
2079fn parent_path(path: &str) -> Option<String> {
2080    let p = Path::new(path).parent()?;
2081    let s = p.to_string_lossy().replace('\\', "/");
2082    if s.is_empty() || s == "." {
2083        None
2084    } else {
2085        Some(s)
2086    }
2087}
2088
2089/// Slug a title the way `nb` 7.24.0 does (ASCII locale): ASCII `A-Z` is
2090/// lowercased, non-ASCII is preserved verbatim, ASCII non-alphanumeric maps
2091/// to `_`, runs collapse, leading/trailing `_` trim.
2092pub(crate) fn mangle_stem(title: &str) -> String {
2093    let mut out = String::with_capacity(title.len());
2094    let mut prev_underscore = false;
2095    for c in title.chars() {
2096        if c.is_ascii_alphanumeric() {
2097            out.push(c.to_ascii_lowercase());
2098            prev_underscore = false;
2099        } else if c.is_ascii() {
2100            if !prev_underscore {
2101                out.push('_');
2102                prev_underscore = true;
2103            }
2104        } else {
2105            out.push(c);
2106            prev_underscore = false;
2107        }
2108    }
2109    out.trim_matches('_').to_string()
2110}
2111
2112/// Titleless filename stem in process-local time (`%Y%m%d%H%M%S`), matching
2113/// `nb`'s `date` (not UTC). Shells out to `date` so `TZ` handling matches
2114/// `nb` exactly; falls back to epoch seconds on failure.
2115pub(crate) fn titleless_stem() -> String {
2116    if let Ok(out) = std::process::Command::new("date")
2117        .arg("+%Y%m%d%H%M%S")
2118        .output()
2119        && out.status.success()
2120    {
2121        let s = String::from_utf8_lossy(&out.stdout).trim().to_string();
2122        if s.len() == 14 && s.bytes().all(|b| b.is_ascii_digit()) {
2123            return s;
2124        }
2125    }
2126    // Fallback: zero-padded epoch seconds (14 chars) + process-unique suffix.
2127    static COUNTER: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0);
2128    let secs = SystemTime::now()
2129        .duration_since(UNIX_EPOCH)
2130        .map(|d| d.as_secs())
2131        .unwrap_or(0);
2132    let n = COUNTER.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
2133    format!("{secs:014}-{n}")
2134}
2135
2136/// Filename for a one-shot create: mangled title stem (or local-time
2137/// titleless stem when `title` is `None`/blank/fully-punctuated) + extension.
2138///
2139/// `extension` is the dotted kind suffix without leading dot (`md`,
2140/// `todo.md`, `bookmark.md`). Collision `-N` suffixing happens at commit
2141/// time via retry in the one-shot wrappers.
2142pub(crate) fn filename_for_title(title: Option<&str>, extension: &str) -> String {
2143    let stem = title
2144        .map(|t| mangle_stem(t.trim()))
2145        .filter(|s| !s.is_empty());
2146    match stem {
2147        Some(s) => format!("{s}.{extension}"),
2148        None => format!("{}.{extension}", titleless_stem()),
2149    }
2150}
2151
2152/// Insert `-N` before the extension (`foo.md` -> `foo-1.md`).
2153pub(crate) fn suffixed_filename(filename: &str, n: u32) -> String {
2154    match filename.find('.') {
2155        Some(i) => format!("{}-{n}{}", &filename[..i], &filename[i..]),
2156        None => format!("{filename}-{n}"),
2157    }
2158}
2159
2160pub(crate) fn join_folder_file(folder: Option<&str>, filename: &str) -> String {
2161    match folder {
2162        Some(f) if !f.trim().is_empty() => {
2163            format!("{}/{}", normalize_rel(f), filename.trim_start_matches('/'))
2164        }
2165        _ => filename.to_string(),
2166    }
2167}
2168
2169/// Split a notebook-relative path into `(folder, basename)`.
2170fn split_folder_basename(path: &str) -> (String, String) {
2171    match path.rfind('/') {
2172        Some(i) => (path[..i].to_string(), path[i + 1..].to_string()),
2173        None => (String::new(), path.to_string()),
2174    }
2175}
2176
2177/// Notebook-relative `.index` path for a folder (`""` -> `.index`).
2178fn index_rel_for_folder(folder: &str) -> String {
2179    if folder.is_empty() {
2180        ".index".to_string()
2181    } else {
2182        format!("{folder}/.index")
2183    }
2184}
2185
2186fn append_index_edit(path: &str) -> PendingIndexEdit {
2187    let (folder, basename) = split_folder_basename(path);
2188    PendingIndexEdit {
2189        file_rel: index_rel_for_folder(&folder),
2190        kind: PendingIndexKind::Append { basename },
2191    }
2192}
2193
2194fn blank_index_edit(path: &str) -> PendingIndexEdit {
2195    let (folder, basename) = split_folder_basename(path);
2196    PendingIndexEdit {
2197        file_rel: index_rel_for_folder(&folder),
2198        kind: PendingIndexKind::Blank { basename },
2199    }
2200}
2201
2202fn move_index_edits(from: &str, to: &str) -> Vec<PendingIndexEdit> {
2203    let (from_folder, from_base) = split_folder_basename(from);
2204    let (to_folder, to_base) = split_folder_basename(to);
2205    if from_folder == to_folder {
2206        vec![PendingIndexEdit {
2207            file_rel: index_rel_for_folder(&from_folder),
2208            kind: PendingIndexKind::Rename {
2209                old_basename: from_base,
2210                new_basename: to_base,
2211            },
2212        }]
2213    } else {
2214        vec![
2215            PendingIndexEdit {
2216                file_rel: index_rel_for_folder(&from_folder),
2217                kind: PendingIndexKind::Blank {
2218                    basename: from_base,
2219                },
2220            },
2221            PendingIndexEdit {
2222                file_rel: index_rel_for_folder(&to_folder),
2223                kind: PendingIndexKind::Append { basename: to_base },
2224            },
2225        ]
2226    }
2227}
2228
2229/// Parse `.index` bytes into positional lines.
2230///
2231/// Trailing-newline terminated content splits cleanly; a missing trailing
2232/// newline still yields its tail as a line. Empty content yields no lines.
2233fn parse_index_lines(bytes: &[u8]) -> Vec<String> {
2234    if bytes.is_empty() {
2235        return Vec::new();
2236    }
2237    let text = String::from_utf8_lossy(bytes);
2238    let mut lines: Vec<String> = text.split('\n').map(str::to_string).collect();
2239    if text.ends_with('\n') {
2240        lines.pop();
2241    }
2242    lines
2243}
2244
2245fn render_index_lines(lines: &[String]) -> Vec<u8> {
2246    if lines.is_empty() {
2247        return Vec::new();
2248    }
2249    let mut out = lines.join("\n").into_bytes();
2250    out.push(b'\n');
2251    out
2252}
2253
2254/// Numeric selector for a post-write placement (`nb:3`, `nb:work/3`).
2255fn numeric_selector(notebook: &str, folder: &str, id: u32) -> String {
2256    if folder.is_empty() {
2257        format!("{notebook}:{id}")
2258    } else {
2259        format!("{notebook}:{folder}/{id}")
2260    }
2261}
2262
2263/// Notebook-relative `.index` files are managed post-materialize under the
2264/// `.nb-api-index.lock`, so the generic tree write must not clobber them
2265/// with its stale snapshot.
2266fn is_index_rel(rel: &str) -> bool {
2267    rel == ".index" || rel.ends_with("/.index")
2268}
2269
2270/// Guard for the notebook-scoped `.nb-api-index.lock`.
2271///
2272/// Serializes nb-api writers against each other for the `.index` read-append
2273/// critical section only (never held across `git add`/`commit`). It does NOT
2274/// serialize external `nb` processes; the cross-process guarantee comes from
2275/// `O_APPEND` plus the rewrite merge loop, with post-write re-read for the
2276/// selector.
2277///
2278/// The lock file carries a unique nonce (`pid`, process-unique counter,
2279/// timestamp). `Drop` removes the file ONLY if it still holds our nonce, so
2280/// a slow holder reaped as "stale" can never delete the lock file a
2281/// replacement writer created afterwards.
2282///
2283/// A live holder refreshes the file mtime on a `timeout/3` heartbeat, so a
2284/// lock that is both older than `timeout` and content-stable is genuinely
2285/// dead — never a live holder. The heartbeat stops itself if the file no
2286/// longer holds our nonce (we were reaped despite everything; refreshing a
2287/// foreign lock would only delay its legitimate reap).
2288struct IndexLockGuard {
2289    path: PathBuf,
2290    nonce: String,
2291    heartbeat: Option<tokio::task::JoinHandle<()>>,
2292}
2293
2294impl Drop for IndexLockGuard {
2295    fn drop(&mut self) {
2296        if let Some(handle) = self.heartbeat.take() {
2297            handle.abort();
2298        }
2299        if std::fs::read_to_string(&self.path)
2300            .map(|content| content.trim_end() == self.nonce)
2301            .unwrap_or(false)
2302        {
2303            let _ = std::fs::remove_file(&self.path);
2304        }
2305    }
2306}
2307
2308fn index_lock_path(notebook_root: &Path) -> PathBuf {
2309    notebook_root.join(".nb-api-index.lock")
2310}
2311
2312fn new_lock_nonce() -> String {
2313    static COUNTER: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0);
2314    let n = COUNTER.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
2315    let nanos = SystemTime::now()
2316        .duration_since(UNIX_EPOCH)
2317        .map(|d| d.as_nanos())
2318        .unwrap_or(0);
2319    format!("pid={} nonce={n} ns={nanos}", std::process::id())
2320}
2321
2322/// Remove the lock file only if it is stale (mtime older than `timeout`) AND
2323/// its content is unchanged across the check, so a live holder that just
2324/// created (or just refreshed) the file is never reaped.
2325///
2326/// Returns true when no lock file remains (absent or reaped).
2327fn try_remove_lock_if_stale(path: &Path, timeout: Duration) -> bool {
2328    let content_before = std::fs::read_to_string(path).ok();
2329    let stale = std::fs::metadata(path)
2330        .and_then(|m| m.modified())
2331        .map(|t| t.elapsed().unwrap_or(Duration::ZERO) > timeout)
2332        .unwrap_or(false);
2333    if !stale {
2334        return content_before.is_none();
2335    }
2336    // Re-read: only reap when the content is identical (no live writer
2337    // replaced it between our reads) and still stale.
2338    let content_after = std::fs::read_to_string(path).ok();
2339    if content_after != content_before {
2340        return false;
2341    }
2342    let still_stale = std::fs::metadata(path)
2343        .and_then(|m| m.modified())
2344        .map(|t| t.elapsed().unwrap_or(Duration::ZERO) > timeout)
2345        .unwrap_or(true);
2346    if content_before.is_none() || !still_stale {
2347        return content_before.is_none();
2348    }
2349    std::fs::remove_file(path).is_ok()
2350}
2351
2352/// Best-effort reap of a stale lock left by a crashed writer, before the
2353/// dirty-baseline check (an untracked lock file would otherwise read dirty).
2354/// Only reaps when the file is older than `timeout` with stable content; a
2355/// live holder's fresh lock is left alone (and then correctly fails the
2356/// dirty check until its owner finishes and removes it).
2357fn reap_stale_index_lock(notebook_root: &Path, timeout: Duration) {
2358    let path = index_lock_path(notebook_root);
2359    if path.exists() {
2360        try_remove_lock_if_stale(&path, timeout);
2361    }
2362}
2363
2364async fn acquire_index_lock(
2365    notebook_root: &Path,
2366    timeout: Duration,
2367) -> Result<IndexLockGuard, NbError> {
2368    // The critical section is millisecond-scale local IO while `timeout`
2369    // defaults to 60s, so reaping below only triggers for genuinely dead
2370    // holders, not slow live ones.
2371    let path = index_lock_path(notebook_root);
2372    let start = Instant::now();
2373    loop {
2374        match OpenOptions::new().write(true).create_new(true).open(&path) {
2375            Ok(mut f) => {
2376                let nonce = new_lock_nonce();
2377                let _ = writeln!(f, "{nonce}");
2378                drop(f);
2379                // Heartbeat: a live holder must never look stale. Refresh
2380                // mtime every timeout/3 (at least every 30s for huge
2381                // timeouts, at most every 5ms to avoid spin on tiny ones).
2382                let beat = (timeout / 3).clamp(Duration::from_millis(5), Duration::from_secs(30));
2383                let heartbeat_path = path.clone();
2384                let heartbeat_nonce = nonce.clone();
2385                let heartbeat = tokio::spawn(async move {
2386                    loop {
2387                        tokio::time::sleep(beat).await;
2388                        let owned = std::fs::read_to_string(&heartbeat_path)
2389                            .map(|content| content.trim_end() == heartbeat_nonce)
2390                            .unwrap_or(false);
2391                        if !owned {
2392                            break;
2393                        }
2394                        if std::fs::File::options()
2395                            .write(true)
2396                            .open(&heartbeat_path)
2397                            .and_then(|f| f.set_modified(SystemTime::now()))
2398                            .is_err()
2399                        {
2400                            break;
2401                        }
2402                    }
2403                });
2404                return Ok(IndexLockGuard {
2405                    path,
2406                    nonce,
2407                    heartbeat: Some(heartbeat),
2408                });
2409            }
2410            Err(e) if e.kind() == std::io::ErrorKind::AlreadyExists => {
2411                if try_remove_lock_if_stale(&path, timeout) {
2412                    continue;
2413                }
2414                if start.elapsed() >= timeout {
2415                    return Err(NbError::IndexLockTimeout {
2416                        path: path.to_string_lossy().into_owned(),
2417                        timeout_ms: timeout.as_millis() as u64,
2418                    });
2419                }
2420                tokio::time::sleep(Duration::from_millis(10)).await;
2421            }
2422            Err(e) => {
2423                return Err(NbError::Io {
2424                    path: path.clone(),
2425                    source: e.into(),
2426                });
2427            }
2428        }
2429    }
2430}
2431
2432/// Placement of one `.index` line after application: 1-based line number.
2433#[derive(Debug, Clone)]
2434struct IndexPlacement {
2435    op_index: u32,
2436    folder: String,
2437    id: u32,
2438}
2439
2440/// Apply pending `.index` edits to fresh on-disk content under the lock.
2441///
2442/// Pure-append files use `O_APPEND` so a concurrent external `nb add` line is
2443/// never clobbered. Files needing blank/rename go through a merge loop:
2444/// our mutations are re-applied onto the latest on-disk content until a
2445/// read-after-write shows no change, so external `O_APPEND` lines that land
2446/// mid-update are preserved, never overwritten. If the file never settles
2447/// (continuous concurrent writers), returns `IndexLockTimeout` instead of
2448/// risking a loss. Returns post-write placements (last occurrence of each
2449/// basename, which is unique per the collision-suffix rule).
2450fn apply_index_edits(
2451    notebook_root: &Path,
2452    pending: &[(u32, PendingIndexEdit)],
2453    contention_timeout: Duration,
2454) -> Result<Vec<IndexPlacement>, NbError> {
2455    // Group by file, preserving plan order within each file.
2456    let mut order: Vec<String> = Vec::new();
2457    let mut grouped: HashMap<String, Vec<(u32, &PendingIndexEdit)>> = HashMap::new();
2458    for (op_index, edit) in pending {
2459        grouped
2460            .entry(edit.file_rel.clone())
2461            .or_insert_with(|| {
2462                order.push(edit.file_rel.clone());
2463                Vec::new()
2464            })
2465            .push((*op_index, edit));
2466    }
2467    let mut placements: Vec<IndexPlacement> = Vec::new();
2468    for file_rel in &order {
2469        let edits = &grouped[file_rel];
2470        let abs = notebook_root.join(file_rel);
2471        let append_only = edits
2472            .iter()
2473            .all(|(_, e)| matches!(e.kind, PendingIndexKind::Append { .. }));
2474        if append_only {
2475            // O_APPEND path: concurrent external appends interleave safely.
2476            if let Some(parent) = abs.parent() {
2477                std::fs::create_dir_all(parent).map_err(|e| NbError::Io {
2478                    path: parent.to_path_buf(),
2479                    source: e.into(),
2480                })?;
2481            }
2482            let mut f = OpenOptions::new()
2483                .create(true)
2484                .append(true)
2485                .open(&abs)
2486                .map_err(|e| NbError::Io {
2487                    path: abs.clone(),
2488                    source: e.into(),
2489                })?;
2490            for (op_index, edit) in edits {
2491                let PendingIndexKind::Append { basename } = &edit.kind else {
2492                    unreachable!()
2493                };
2494                writeln!(f, "{basename}").map_err(|e| NbError::Io {
2495                    path: abs.clone(),
2496                    source: e.into(),
2497                })?;
2498                let _ = op_index;
2499            }
2500        } else {
2501            // Lossless rewrite vs concurrent appenders (see
2502            // `merge_index_rewrite`): never a truncate-write-verify.
2503            if let Some(parent) = abs.parent() {
2504                std::fs::create_dir_all(parent).map_err(|e| NbError::Io {
2505                    path: parent.to_path_buf(),
2506                    source: e.into(),
2507                })?;
2508            }
2509            let appends: Vec<&String> = edits
2510                .iter()
2511                .filter_map(|(_, e)| match &e.kind {
2512                    PendingIndexKind::Append { basename } => Some(basename),
2513                    _ => None,
2514                })
2515                .collect();
2516            let mutations: Vec<&PendingIndexEdit> = edits
2517                .iter()
2518                .map(|(_, e)| *e)
2519                .filter(|e| !matches!(e.kind, PendingIndexKind::Append { .. }))
2520                .collect();
2521            merge_index_rewrite(&abs, &appends, &mutations, contention_timeout)?;
2522        }
2523        // Post-write re-read: last occurrence wins (basenames unique).
2524        let fresh = std::fs::read(&abs).map_err(|e| NbError::Io {
2525            path: abs.clone(),
2526            source: e.into(),
2527        })?;
2528        let lines = parse_index_lines(&fresh);
2529        for (op_index, edit) in edits {
2530            let (folder, basename) = match &edit.kind {
2531                PendingIndexKind::Append { basename } => {
2532                    let (folder, _) =
2533                        split_folder_basename(&pending_basename_path(file_rel, basename));
2534                    (folder, basename.clone())
2535                }
2536                PendingIndexKind::Blank { basename } => {
2537                    let (folder, _) =
2538                        split_folder_basename(&pending_basename_path(file_rel, basename));
2539                    (folder, basename.clone())
2540                }
2541                PendingIndexKind::Rename { new_basename, .. } => {
2542                    let (folder, _) =
2543                        split_folder_basename(&pending_basename_path(file_rel, new_basename));
2544                    (folder, new_basename.clone())
2545                }
2546            };
2547            if let Some(pos) = lines.iter().rposition(|l| l == &basename) {
2548                placements.push(IndexPlacement {
2549                    op_index: *op_index,
2550                    folder,
2551                    id: pos as u32 + 1,
2552                });
2553            } else if let PendingIndexKind::Blank { .. } = &edit.kind {
2554                // Blank target missing from a fresh external index: fall back
2555                // to the virtual position so deletes of unindexed files still
2556                // report a selector echo without an id.
2557                let _ = folder;
2558            }
2559        }
2560    }
2561    Ok(placements)
2562}
2563
2564/// Rewrite one `.index` file with blank/rename mutations.
2565///
2566/// Where the platform offers atomic range removal (Linux
2567/// `FALLOC_FL_COLLAPSE_RANGE`, verified per file at runtime), the rewrite is
2568/// lossless against concurrent O_APPEND writers (external `nb add`): the
2569/// mutated prefix (never longer than its base — same-folder growing renames
2570/// are refused at plan time) is overwritten in place while concurrent
2571/// appends live beyond it; the observed tail is copied forward and the stale
2572/// middle range is removed with a single atomic `collapse_range` that the
2573/// kernel serializes against appends. Any size movement retries the round
2574/// (mutations are idempotent; our basenames are unique so appends are never
2575/// duplicated). There is no truncate-write-verify window: no appended line
2576/// can be destroyed undetectably.
2577///
2578/// Where the platform lacks atomic range removal, the stale range is removed
2579/// with truncate: the race is narrowed to that single syscall boundary with
2580/// retry on any observed growth, and `IndexLockTimeout` refusal under
2581/// sustained contention — a documented residual micro-window, not covered by
2582/// the no-loss guarantee (see the note-identity specification, item 6).
2583///
2584/// A rename that still GROWS the file can only arrive via re-attached
2585/// appends after an external rewrite dropped ours, and falls back to a
2586/// whole write with post-verify — same documented residual.
2587///
2588/// Concurrent external REWRITES (another blank/rename, e.g. external `nb
2589/// delete`) are out of scope: without `nb` cooperation no protocol can
2590/// serialize them; same as nb-vs-nb. If the file never settles, returns
2591/// `IndexLockTimeout` instead of risking a loss.
2592fn merge_index_rewrite(
2593    abs: &Path,
2594    appends: &[&String],
2595    mutations: &[&PendingIndexEdit],
2596    contention_timeout: Duration,
2597) -> Result<(), NbError> {
2598    use std::io::{Read as _, Seek as _, Write as _};
2599    let io_err = |e: std::io::Error| NbError::Io {
2600        path: abs.to_path_buf(),
2601        source: e.into(),
2602    };
2603    let mut fd = OpenOptions::new()
2604        .read(true)
2605        .write(true)
2606        .create(true)
2607        .truncate(false)
2608        .open(abs)
2609        .map_err(io_err)?;
2610    for _ in 0..25 {
2611        let s0 = fd.metadata().map_err(io_err)?.len();
2612        fd.seek(std::io::SeekFrom::Start(0)).map_err(io_err)?;
2613        let mut base = Vec::new();
2614        fd.read_to_end(&mut base).map_err(io_err)?;
2615        if fd.metadata().map_err(io_err)?.len() != s0 {
2616            continue; // grew mid-read; nothing written yet
2617        }
2618        #[cfg(feature = "testing")]
2619        if let Ok(ms) = std::env::var("NB_API_INDEX_SPLICE_PAUSE_MS")
2620            && let Ok(ms) = ms.parse::<u64>()
2621        {
2622            // Testing only: hold the read-to-splice window open so a
2623            // concurrent external O_APPEND deterministically lands inside
2624            // it. External writers take no lock, so they are unaffected.
2625            std::thread::sleep(Duration::from_millis(ms));
2626        }
2627        let mut lines = parse_index_lines(&base);
2628        for edit in mutations {
2629            match &edit.kind {
2630                PendingIndexKind::Append { .. } => {}
2631                PendingIndexKind::Blank { basename } => {
2632                    if let Some(pos) = lines.iter().position(|l| l == basename) {
2633                        lines[pos] = String::new();
2634                    }
2635                }
2636                PendingIndexKind::Rename {
2637                    old_basename,
2638                    new_basename,
2639                } => {
2640                    if let Some(pos) = lines.iter().position(|l| l == old_basename) {
2641                        lines[pos] = new_basename.clone();
2642                    }
2643                }
2644            }
2645        }
2646        for basename in appends {
2647            if !lines.iter().any(|l| l == *basename) {
2648                lines.push((*basename).clone());
2649            }
2650        }
2651        let rendered = render_index_lines(&lines);
2652        if rendered.as_slice() == base.as_slice() {
2653            return Ok(()); // already applied; nothing to write
2654        }
2655        if rendered.len() as u64 > s0 {
2656            // Growing rewrite: only reachable via re-attached appends after
2657            // an external rewrite dropped ours (same-folder growing renames
2658            // are refused at plan time). Whole write + verify fallback with
2659            // a documented residual micro-window.
2660            fd.seek(std::io::SeekFrom::Start(0)).map_err(io_err)?;
2661            fd.write_all(&rendered).map_err(io_err)?;
2662            fd.set_len(rendered.len() as u64).map_err(io_err)?;
2663            if fd.metadata().map_err(io_err)?.len() == rendered.len() as u64 {
2664                return Ok(());
2665            }
2666            continue;
2667        }
2668        // Shrink splice: the prefix overwrite cannot reach appender bytes
2669        // (they live at offsets >= s0 >= rendered length).
2670        let prefix_len = rendered.len() as u64;
2671        fd.seek(std::io::SeekFrom::Start(0)).map_err(io_err)?;
2672        fd.write_all(&rendered).map_err(io_err)?;
2673        if fd.metadata().map_err(io_err)?.len() != s0 {
2674            continue; // grew during prefix write; their bytes untouched
2675        }
2676        // Copy the concurrent tail [s0, s1) forward behind our prefix.
2677        let s1 = fd.metadata().map_err(io_err)?.len();
2678        fd.seek(std::io::SeekFrom::Start(s0)).map_err(io_err)?;
2679        if fd.metadata().map_err(io_err)?.len() != s1 {
2680            continue;
2681        }
2682        let mut tail = Vec::new();
2683        let mut take = (s1 - s0) as usize;
2684        while take > 0 {
2685            let mut chunk = vec![0u8; take.min(8192)];
2686            let n = fd.read(&mut chunk).map_err(io_err)?;
2687            if n == 0 {
2688                break;
2689            }
2690            tail.extend_from_slice(&chunk[..n]);
2691            take -= n;
2692        }
2693        if fd.metadata().map_err(io_err)?.len() != s1 {
2694            continue;
2695        }
2696        #[cfg(feature = "testing")]
2697        if let Ok(ms) = std::env::var("NB_API_INDEX_SPLICE_PAUSE_MS")
2698            && let Ok(ms) = ms.parse::<u64>()
2699        {
2700            // Testing only: hold the tail-splice window open too, so a
2701            // concurrent external O_APPEND deterministically lands inside
2702            // it as well as the read-to-prefix window above.
2703            std::thread::sleep(Duration::from_millis(ms));
2704        }
2705        fd.seek(std::io::SeekFrom::Start(prefix_len))
2706            .map_err(io_err)?;
2707        fd.write_all(&tail).map_err(io_err)?;
2708        // Remove the stale region [prefix_len + tail, s0) and shift the
2709        // external tail left. collapse_range is a single syscall the kernel
2710        // serializes against concurrent appends: they land wholly before
2711        // (shifted left, preserved) or wholly after (at the new end,
2712        // preserved) — either way the post-check size mismatch retries
2713        // with their bytes present. No truncate-then-verify window.
2714        let tail_len = tail.len() as u64;
2715        let stale_len = s0.saturating_sub(prefix_len + tail_len);
2716        let expected = prefix_len + (s1 - s0);
2717        let collapsed = collapse_stale_range(&fd, prefix_len + tail_len, stale_len);
2718        if !collapsed {
2719            // Portable fallback (non-Linux, or filesystems without
2720            // collapse support): truncate with a documented residual
2721            // micro-window vs racing appends.
2722            fd.set_len(prefix_len + tail_len).map_err(io_err)?;
2723        }
2724        if fd.metadata().map_err(io_err)?.len() == expected {
2725            return Ok(());
2726        }
2727        // Size moved during removal; retry onto the new content.
2728    }
2729    Err(NbError::IndexLockTimeout {
2730        path: abs.to_string_lossy().into_owned(),
2731        timeout_ms: contention_timeout.as_millis() as u64,
2732    })
2733}
2734
2735/// Remove the byte range [offset, offset+len), shifting the tail left.
2736///
2737/// Single syscall (`FALLOC_FL_COLLAPSE_RANGE`): the kernel serializes it
2738/// against concurrent O_APPEND writes, which land wholly before (shifted
2739/// left along with the tail — preserved) or wholly after (at the new end —
2740/// preserved). Either way a post-check size mismatch retries with their
2741/// bytes present, so unlike truncate-then-verify there is no window in
2742/// which an appended line can be destroyed undetectably.
2743///
2744/// Returns true when the range is gone (or was empty). Returns false when
2745/// the platform/filesystem cannot do it — caller falls back to truncate
2746/// with a documented residual micro-window.
2747#[cfg(target_os = "linux")]
2748fn collapse_stale_range(fd: &std::fs::File, offset: u64, len: u64) -> bool {
2749    use std::os::fd::AsRawFd;
2750    if len == 0 {
2751        return true;
2752    }
2753    const FALLOC_FL_COLLAPSE_RANGE: libc::c_int = 0x08;
2754    let r = unsafe {
2755        libc::fallocate(
2756            fd.as_raw_fd(),
2757            FALLOC_FL_COLLAPSE_RANGE,
2758            offset as libc::off_t,
2759            len as libc::off_t,
2760        )
2761    };
2762    r == 0
2763}
2764
2765/// Non-collapse platforms always report unavailable; the caller falls back
2766/// to truncate with a documented residual micro-window.
2767#[cfg(not(target_os = "linux"))]
2768fn collapse_stale_range(_fd: &std::fs::File, _offset: u64, _len: u64) -> bool {
2769    false
2770}
2771
2772/// Recover the folder owning `file_rel` for placement reporting.
2773fn pending_basename_path(file_rel: &str, basename: &str) -> String {
2774    if file_rel == ".index" {
2775        basename.to_string()
2776    } else if let Some(folder) = file_rel.strip_suffix("/.index") {
2777        format!("{folder}/{basename}")
2778    } else {
2779        basename.to_string()
2780    }
2781}
2782
2783/// Scan a notebook-relative `.index` on disk for `basename`; blank lines are
2784/// skipped (deleted ids stay dead, never reused).
2785fn index_id_on_disk(notebook_root: &Path, rel_path: &str) -> Option<u32> {
2786    let (folder, basename) = split_folder_basename(rel_path);
2787    index_id_in_folder(notebook_root, &folder, &basename)
2788}
2789
2790/// Numeric id of `basename` in `folder`'s on-disk `.index`, if listed.
2791pub(crate) fn index_id_in_folder(
2792    notebook_root: &Path,
2793    folder: &str,
2794    basename: &str,
2795) -> Option<u32> {
2796    let abs = notebook_root.join(index_rel_for_folder(folder));
2797    let bytes = std::fs::read(abs).ok()?;
2798    parse_index_lines(&bytes)
2799        .iter()
2800        .position(|l| l == basename)
2801        .map(|p| p as u32 + 1)
2802}